WordPress Hook Architecture

Hook Architecture Overview

The Private Comments plugin integrates with the WordPress database layer to ensure privacy is enforced globally across the site. By leveraging core WordPress filters, the plugin modifies the SQL generated for comment queries before they are executed. This ensures that privacy is maintained not only in front-end templates but also in the WordPress Admin dashboard, REST API endpoints, and AJAX calls.

Core Database Interception

The plugin's primary functionality is driven by the comments_clauses filter. This allows the plugin to inject custom SQL logic into the WP_Comment_Query class.

comments_clauses

This filter is used to modify the SQL clauses (JOIN, WHERE, GROUP BY, ORDER BY, LIMIT) for comment queries.

• Logic: The plugin checks if the current user has administrative privileges or is the author of the post being viewed. If neither condition is met, the WHERE clause is modified to include only comments where the user_id matches the current logged-in user or where the comment author's email matches the current user's email.
• Inputs:
  • $clauses (array): An associative array of SQL clauses.
  • $query (WP_Comment_Query): The current query object.
• Output: Returns the modified $clauses array.

/**
 * Example of how the plugin modifies comment queries:
 * If the user is not an admin/post author, the SQL 'where' clause 
 * is updated to restrict results.
 */
$clauses['where'] .= $wpdb->prepare(
    " AND (user_id = %d OR comment_author_email = %s)",
    $current_user_id,
    $current_user_email
);

Adjusting Comment Counts

To prevent "ghost notifications" (where a post shows a comment count that doesn't match the visible comments), the plugin hooks into the metadata and count functions.

wp_count_comments

This filter intercepts the total count of comments for a specific post or for the entire site.

• Role: It ensures that the comment count bubbles in the Admin Bar and Post lists reflect only the comments the current user is authorized to see.
• Type: Filter
• Usage: Automatically applied whenever get_comments_number() or wp_count_comments() is called.

Internal Logic & Execution Flow

While the plugin's internal methods are encapsulated to prevent namespace collisions, the following flow describes how the architecture handles a request:

1. Authentication Check: The plugin identifies the WP_User object of the person making the request.
2. Context Identification: It determines if the request is for the front-end or the WordPress Admin dashboard.
3. Privilege Evaluation:
   • If current_user_can('manage_options'), the filters are bypassed to allow administrators full visibility.
   • If the user is the post author ($post->post_author == $user_id), filters are bypassed for that specific post.
4. SQL Modification: If the user is a standard visitor or subscriber, the comments_clauses are injected with the restriction logic.

Extensibility for Developers

Developers can interact with the plugin's visibility logic by using standard WordPress query variables. Since the plugin modifies the WP_Comment_Query, any custom instance of get_comments() will respect these privacy settings unless specifically bypassed.

Bypassing Privacy in Custom Queries

If you are developing a custom administrative tool and need to fetch all comments regardless of the plugin's restrictions, you should ensure your code runs with high-level capabilities or temporarily remove the plugin's filters:

// Example: Temporarily removing the filter for a custom background process
remove_filter('comments_clauses', [ 'PrivateComments\Plugin', 'filter_comment_queries' ], 10);

$all_comments = get_comments([ 'post_id' => 123 ]);

// Re-add the filter to maintain site security
add_filter('comments_clauses', [ 'PrivateComments\Plugin', 'filter_comment_queries' ], 10, 2);

(Note: The specific class and method names above are illustrative of standard plugin architecture.)