comments-through-cache is a WordPress must-use plugin for sites served from a page cache. It is for operators who moderate comments and run nginx, Varnish, a cache plugin or a CDN in front of PHP. It is MIT licensed, and v0.1.0 was released on 14 November 2026.
WordPress shows a reader their own held comment in two ways. The first is the commenter cookies, which carry the author’s email address. The second is the redirect URL core sends after posting, which carries unapproved and moderation-hash query arguments and works only for a short time.
Core sets the cookies only when the reader ticks the “save my name, email and website” box. When the box is not posted, core expires the cookies. Many themes drop that box without meaning to. On such a site the reader posts, sees “awaiting moderation” on the redirect URL, refreshes the clean article URL and finds the comment gone. They assume it was lost and post it again.
A page cache makes this worse in three ways. The clean URL is served from cache, so even a reader with the cookies sees the cached copy. An approved comment reaches other readers only when the cached copy expires, so moderators think approval failed. And if a cache stores the redirect URL, any visitor with that URL sees one reader’s held comment. Turning the cache off is not an answer, so the plugin works with it.
action, http, file, cloudflare) and example cache rules for nginx FastCGI cache, Varnish and a Cloudflare Cache Rule.Plugin::boot() builds each object and registers the hooks once. After a comment is posted, core fires set_comment_cookies and, without consent, sends expiring cookies at priority 10. CookieSetter runs at priority 20 and sends the email cookie with a one day lifetime. Browsers apply Set-Cookie headers in order, so the later one wins. A small HttpOnly marker cookie holds only a timestamp and records that the plugin set the cookie, not the reader’s consent.
On later requests the cookie makes the cache bypass, core finds the reader’s held comments by email, and HeldNotice prints the notice. When the reader has no held comments left on the site, and at least five minutes have passed, the plugin expires its own cookies. For the redirect URL the plugin does not reimplement the hash check. It calls core’s wp_get_unapproved_comment_author_email(), so the validity window is whatever the installed core says.
For moderation, ModerationListener queues the post on transition_comment_status and edit_comment. At shutdown, after the response is sent where PHP-FPM allows, PurgeQueue builds each post’s purge set through PurgeUrlCollector. The set is the permalink, the comment pages that exist plus one (capped at ten) and the comments feed. The queue merges the sets, removes duplicates and gives each purger one call. Every origin purger finishes before any edge purger starts, so the CDN cannot refetch a stale origin copy.
The file purger recomputes the nginx cache file name from the cache key and levels, and removes the GET and HEAD entries. It needs a cache key that includes the method:
fastcgi_cache_key "$scheme$request_method$host$request_uri";
Purgers are chosen in wp-config.php:
define('COMMENTS_THROUGH_CACHE_PURGERS', 'file,cloudflare');
define('COMMENTS_THROUGH_CACHE_FILE_PATH', '/var/cache/nginx/wordpress');
define('COMMENTS_THROUGH_CACHE_CF_ZONE_ID', '<your-zone-id>');
define('COMMENTS_THROUGH_CACHE_CF_API_TOKEN', '<your-api-token>');
The plugin cannot make a cache do anything, so the README lists four rules every cache in front of PHP must follow. Do not serve or store a request with a comment_author_ cookie. Do not serve or store a request with unapproved= or moderation-hash= in the query. Never store a response with Set-Cookie. Cache only GET and HEAD.
comments_through_cache_should_set_cookie, turns the cookie off entirely. The rest of the plugin works without it. The README gives cookie policy wording and tells operators to confirm the decision with their own counsel. The plugin makes no legal ruling.Set-Cookie without no-store headers, so a cache that broke the no-Set-Cookie rule could replay the expiry and wipe other readers’ cookies. It now sends Cache-Control: private, no-store, max-age=0 and X-Accel-Expires: 0.config command also now masks user:password@ in the HTTP endpoint.wp-comments-post.php. A form that posts through its own AJAX endpoint gets no cookie and no preview.Test status: this is v0.1.0. The review reports 130 PHPUnit tests, PHPStan level 8 and phpcs all clean on a local PHP 8.3. The tests use stubs, mocks and fake HTTP clients. The CI workflow has not run on GitHub yet, and the plugin has not run on a live site.
As with the other utilities, it was specified, built and reviewed in separate roles by language-model coding agents under the editor’s direction. The editor ruled on each open question.
It needs PHP 8.1 or later and WordPress 6.4 or later. Copy the folder to wp-content/mu-plugins/comments-through-cache/ and add the one-line loader from examples/mu-plugin-loader.php. With Composer:
composer require indianopinion/comments-through-cache
The package is not on Packagist yet, so add a Composer vcs repository entry for https://github.com/IndianOpinion/comments-through-cache first.