nitida/wp-mu-cache

WordPress must-use plugin, installed with Composer, for sites that sit behind an nginx fastcgi_cache. WordPress cannot see that cache, so without this an edit in wp-admin reaches logged-out visitors only when the TTL expires. With it, any change to public content empties the site's zone once, at the end of the request, after the response has been sent.

What triggers a purge

• publish / unpublish / edit / trash / delete of any post of a public type
• attachment edits and deletions
• terms of public taxonomies created, edited, deleted
• menus, widgets, Customizer saves, theme or plugin switches
• options that alter public markup (blogname, front page, permalinks, Polylang, Rank Math, cookie banner, Kadence, theme_mods_*); extend with the nitida_cache_purge_option_pattern filter

One purge per request, whole zone. Per-URL invalidation is deliberately not attempted: at our sizes it is a bug farm, and signed-in users bypass the cache so editors always see the current page.

Polylang: the plugin turns on Polylang's cache-compatible mode (cookie set by JavaScript instead of Set-Cookie), otherwise nginx caches nothing. No-op if Polylang is not installed.

Configure

In the site's .env:

NGINX_CACHE_ZONE=inercia            # the zone name in the nginx vhost
# NGINX_CACHE_PURGE_CMD=...         # optional full override of the default command

Default command: sudo -n /usr/local/sbin/nginx-cache-purge <zone>.

With nothing set (local Docker, a host without nginx cache) the plugin is inert; it logs one line per request that would have purged, so a misconfigured production site shows up in the PHP error log instead of staying silently stale.

Prerequisite on the server

The PHP-FPM pool user must be able to run the purge binary without a password. On a Debian box with the pool running as www-data:

# /etc/sudoers.d/nginx-cache-purge  (mode 0440)
www-data ALL=(root) NOPASSWD: /usr/local/sbin/nginx-cache-purge

Test as that user: sudo -n -u www-data sudo -n /usr/local/sbin/nginx-cache-purge <zone>.

Install (Bedrock)

composer config repositories.wp-mu-cache vcs https://github.com/lintmycode/wp-mu-cache.git
composer require nitida/wp-mu-cache:^1.0

Lands in web/app/mu-plugins/wp-mu-cache/; make sure that directory is gitignored. Bedrock's autoloader loads it, nothing to activate.

CLI

wp nitida cache status           # resolved command, exec() availability
wp nitida cache purge            # empty the zone now (deploy scripts)
wp nitida cache purge --objects  # also flush the object cache