comments-through-cache: held comments behind a page cache

A WordPress must-use plugin that keeps a held comment visible to its author on refresh, and purges only the affected article URLs when a moderator approves or removes a comment.

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.

The problem

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.

What it does

  • Sets a short-lived email cookie for anonymous readers who did not consent to the core cookies, so their held comment survives a refresh and their requests skip the page cache.
  • Sends no-store headers on the redirect URL.
  • Prints a notice above the comment form telling the reader the comment is held.
  • Purges the article’s URLs when a comment enters or leaves the approved state, or when an approved comment is edited.
  • Ships four purgers (action, http, file, cloudflare) and example cache rules for nginx FastCGI cache, Varnish and a Cloudflare Cache Rule.
  • Adds WP-CLI commands and a Site Health test to check that the cache in front of a URL behaves.

How it works

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.

Guard rails

  • The cookie is the email only by default, lasts one day instead of core’s year, and is clamped to between 300 seconds and 30 days. Nothing is set for logged-in users, consenting readers, or comments saved as spam or trash.
  • A filter, 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.
  • The plugin stores nothing in the database and never logs cookie values, email addresses or comment content.
  • Purge failures are logged and never block moderation. The page then updates at its cache TTL. The whole flush has a time budget (default 5 seconds), and each request timeout is cut to the time left.
  • The file purger refuses symbolic links, anything that is not a regular file, and anything outside the resolved cache directory. Hosts other than the site’s own are dropped from purge sets.
  • There is no admin page, AJAX handler or REST route. WP-CLI and Site Health are the only extra surfaces.

What review changed

  • A flush ran every purger once per queued post, so a bulk action on twenty posts sent twenty Cloudflare requests and could exhaust the budget, leaving later posts stale. The flush now merges the sets and calls each purger once per reason.
  • Request timeouts could hold a flush a full timeout past the budget. They are now cut to the time left.
  • The early-expiry response sent 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.
  • An exception from a purge filter at shutdown could become a fatal error. It is now caught and logged. The config command also now masks user:password@ in the HTTP endpoint.

Limits and what is next

  • Themes must submit comments through core’s wp-comments-post.php. A form that posts through its own AJAX endpoint gets no cookie and no preview.
  • Listing pages such as the home page and archives are not purged. A filter lets you add them.
  • A comment posted without an email address cannot be shown through the cookie.
  • There is no settings screen in 0.1.0.
  • One open issue asks whether WordPress 6.9 block notes trigger purges on published posts.

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.

Install

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.

All 47 utilities · comments-through-cache on GitHub

Search Trending
Loading

Signing-in 3 seconds...

Signing-up 3 seconds...

All fields are required.