System Architecture

Architectural Overview

The Private Comments plugin is designed as a lightweight, single-file extension for WordPress. It operates by intercepting the standard WordPress comment retrieval process and applying a visibility filter based on the current user's identity and capabilities.

Rather than modifying the database schema or creating custom tables, the system leverages core WordPress hooks to ensure that data privacy is maintained regardless of which theme or front-end template is used to display comments.

Integration Layer

The system integrates directly with the WordPress Hook API. It primarily utilizes the database query filters to ensure that restricted comments are never sent to the application layer for unauthorized users.

Hook: comments_clauses

The plugin hooks into the comments_clauses filter. This is the primary integration point where the plugin injects custom SQL logic into the comment query.

• Role: Modifies the WHERE clause of the SQL query before it is executed by WP_Comment_Query.
• Impact: By filtering at the database level, the plugin ensures that restricted comments are excluded from the results array entirely, preventing accidental leaks in "Recent Comments" widgets or AJAX calls.

Access Control Logic

The architecture follows a "Least Privilege" model. The system evaluates the following conditions to determine if a comment should be visible:

| User Role/Identity | Visibility Status | Logic Applied | | :--- | :--- | :--- | | Administrator | Visible | Bypasses all filters; sees all comments. | | Post Author | Visible | Can see all comments attached to their specific posts. | | Comment Author | Visible | Can see their own comments (matched by User ID or Email). | | Other Users/Guests | Hidden | Filtered out via SQL WHERE clause. |

Data Flow

1. Request: A user visits a post page or a widget requests a comment list.
2. Query Initialization: WordPress initializes a WP_Comment_Query.
3. Interception: The plugin intercepts the query parameters.
4. Permission Check:
   • The system checks current_user_can('manage_options') for admin status.
   • The system identifies the user_id or email of the requester.
5. SQL Modification: The plugin appends a conditional string to the WHERE clause of the query:

   AND (comment_approved = '1' OR user_id = [CURRENT_USER_ID] OR ...)
   

6. Response: WordPress returns only the authorized subset of comments to the theme template.

Developer Interface

While the plugin is designed to work out-of-the-box without configuration, developers can interact with its state via standard WordPress plugin checks.

Checking Plugin State

To check if the private comment logic is active within a theme or another plugin:

if ( is_plugin_active( 'private-comments/private-comments.php' ) ) {
    // Custom logic for when privacy is enforced
}

Compatibility

The system is designed to be compatible with any theme that uses the standard wp_list_comments() function or get_comments() query. Because the filtering happens at the query level, no modifications to comments.php template files are required.