Edge Cache Headers

Per-template Cache-Control for WordPress, so Cloudflare and nginx can cache anonymous HTML without ever storing a logged-in, preview, cart or cookie-setting page. It makes the decision once, in PHP, per request, and generates the matching nginx and Cloudflare configuration so the three layers agree.

Measured on a news site publishing about 79 posts an hour: before the header, Cloudflare reported DYNAMIC on every HTML request and uncached time to first byte was 1.29 s on the home page; an nginx page-cache hit is about 5 ms.

This project came out of the work on indianopinion.org and is written from scratch; it is independent of and not affiliated with any third-party plugin it integrates with.

Contents

• Install
• Quick start
• What it sends
• Configuration
• Filters and actions
• WP-CLI
• How it works
• Limitations
• FAQ
• Licence

Install

Requires WordPress 6.4 or later and PHP 8.1 or later. No Composer at runtime, no build step.

As a normal plugin

1. Download the release zip, or clone into wp-content/plugins/wp-edge-cache-headers.
2. Activate it (network-activate on multisite if every site should use it).

As a must-use plugin

WordPress loads only top-level files in mu-plugins, so a one-file loader is needed.

1. Copy the plugin directory to wp-content/mu-plugins/wp-edge-cache-headers/.
2. Copy examples/mu-plugin-loader.php to wp-content/mu-plugins/wp-edge-cache-headers-loader.php. It contains one line that matters:

require_once WPMU_PLUGIN_DIR . '/wp-edge-cache-headers/wp-edge-cache-headers.php';

The plugin guards against loading twice, so a normal and a must-use copy cannot both run.

With Composer

composer require indianopinion/wp-edge-cache-headers

With composer/installers the package lands in wp-content/plugins/. Without Composer, require 'autoload.php'; is all the engine needs (see examples/standalone-engine.php).

Quick start

1. Install and activate. Anonymous HTML now carries a Cache-Control with s-maxage.

2. Tell it how busy the site is:

   wp edge-cache suggest-rate --apply

3. Generate and install the nginx snippet (docs/nginx.md):

   wp edge-cache nginx

4. Generate and create the Cloudflare cache rule (docs/cloudflare.md):

   wp edge-cache cloudflare

5. Check a URL:

   wp edge-cache explain https://example.com/hello-world/
   wp edge-cache explain https://example.com/hello-world/ --live

What it sends

Bypass conditions, each with the reason shown in the debug header: logged in (logged-in); a cookie whose name starts with a listed prefix, valid or not (cookie:<prefix>); commerce pages (commerce); an Authorization header (authorization); preview, customiser and page-builder arguments (preview); comment moderation views (moderation); _wpnonce (nonce); password-protected posts (password); non-public post status (non-public-status); methods other than GET and HEAD (method); a Set-Cookie in the response (set-cookie:<name>); login, signup and activation paths (path); Vary on anything but Accept-Encoding (unsafe-vary:<header>); status outside the cacheable list (status:<code>); TTL 0 (ttl-zero); a filter that threw (error); a debug token (debug-token).

Configuration

Settings live under Settings, Edge cache headers (and Network Settings for network defaults). Resolution order, later wins: built-in defaults, network defaults, the site's own settings, constants, filters.

Default TTLs (seconds)

The profile follows the publishing rate: quiet under 1 post an hour, steady 1 to 19 (the default), busy 20 or more.

Search is 0, which means never cached: every search URL is unique and expensive.

Settings

Constants (wp-config.php)

A constant locks its setting; the settings page shows it read-only.

Debugging one request

Rotate a token with wp edge-cache token (shown once, stored as a hash), then:

curl -sI -H 'X-Edge-Cache-Debug-Token: <token>' https://example.com/hello-world/ | grep -i x-edge-cache-debug
# X-Edge-Cache-Debug: outcome=PRIVATE; would-be=PUBLIC; type=singular_post; ttl=1800; swr=9000; sie=86400; status=200; hook=wp_headers; reasons=debug-token

A request with the token is always PRIVATE, so it is never cached, and the generated nginx snippet bypasses on it. The debug header never contains cookie values, user ids, nonces or query values.

Filters and actions

Every filter is prefixed edge_cache_headers_.

Action edge_cache_headers_decided fires once per decision with the Decision, for logging or metrics. See examples/filters.php for recipes.

PHP functions: IndianOpinion\EdgeCacheHeaders\current_decision() returns the current request's Decision (or null before it is made); IndianOpinion\EdgeCacheHeaders\explain( $url, $options ) explains a URL.

A filter that throws makes the response PRIVATE with reason error. A filter that returns an invalid value is ignored and the default is used. The decision filter can turn a PRIVATE decision PUBLIC: do not do that for identified visitors.

WP-CLI

wp edge-cache explain <url> [--method=<m>] [--cookie=<names>] [--logged-in] [--header=<name:value>] [--live] [--format=table|json]
wp edge-cache config
wp edge-cache nginx
wp edge-cache cloudflare
wp edge-cache token
wp edge-cache suggest-rate [--days=7] [--post-type=post] [--apply]

explain exits 0 when the decision was shown (and, with --live, matched), 1 on a live mismatch, 2 on an error such as a URL on a foreign host. If the live request cannot be made (some hosts block loopback requests), it falls back to the simulation and says so.

How it works

The decision engine is a pure PHP class: request facts in, a header set out. The WordPress layer gathers the facts (conditional tags, cookie and query argument names, queued headers) and applies the result.

1. wp_headers (WordPress 6.1 and later run the main query before this filter): the main decision, merged into the header array core is about to send.
2. send_headers: replace any duplicate Cache-Control and remove the Expires and Pragma core queued for 404s.
3. wp_redirect_status: canonical and plugin redirects are re-decided (301 and 308 cacheable, 302, 303 and 307 private).
4. template_include: a late check that only downgrades, for cookies, no-cache headers and status changes that appeared after the main decision.
5. rest_pre_serve_request: REST responses.

Every bypass condition is checked before a TTL is chosen. Core's own no-cache calls (logged-in users, 404s) are recognised and replaced; anyone else's no-cache is respected. Full detail, with every design decision, is in docs/ARCHITECTURE.md; the behaviour contract is docs/PRD.md.

Limitations

• Cookies set and status codes changed while the theme prints, after template_include, cannot be seen without strict mode.
• If output starts before the plugin's hooks (a stray byte before <?php), it cannot send headers. nginx then uses its fallback TTL and Cloudflare, with the recommended rule, bypasses.
• No purging. Expiry plus stale-while-revalidate is the model; purge plugins can coexist.
• No TTL growth with post age yet.
• The nginx contract does not apply to Apache or LiteSpeed; the headers still work there.
• Cloudflare APO uses its own logic and is out of scope.

FAQ

Why is max-age 0? Browsers revalidate HTML every time, so a reader who logs in is never shown an anonymous copy from their own disk cache. Shared caches still hold the page for s-maxage.

My busiest template is never cached. Run wp edge-cache explain on it, or send a debug token. A reason like set-cookie:views means a theme or plugin sets a cookie on anonymous views. Count views with a beacon instead.

A page-cache plugin serves my pages and these headers are missing. Page-cache plugins that serve before WordPress loads skip this plugin entirely. Its headers only appear on responses WordPress renders.

Why not a shorter TTL on a busy site? At about 80 posts an hour a 60 s TTL bought no visible freshness and kept the origin rebuilding. With stale-while-revalidate readers get an instant response while the refresh happens behind them.

I purged Cloudflare and still see the old page. A Cloudflare purge does not purge nginx. Purge nginx first, or rely on the TTLs.

How do I remove everything? Deleting the plugin from the Plugins screen removes its options on every site. For a must-use install, delete the options edge_cache_headers_settings (each site) and edge_cache_headers_network (network) by hand; wp edge-cache config prints both names.

Does it work on multisite? Yes: subdirectory, subdomain and domain-mapped. As a must-use plugin it runs on every site.

Development

See CONTRIBUTING.md. In short: composer install, then composer test, composer stan and composer cs.

Licence

MIT. See LICENSE.