# wp-edge-cache-headers: per-template Cache-Control for WordPress

wp-edge-cache-headers is a WordPress plugin that sends Cache-Control per template, so Cloudflare and nginx can cache anonymous HTML without ever storing a logged-in, preview, cart or cookie-setting page. It is for WordPress site operators. The code is at [https://github.com/IndianOpinion/wp-edge-cache-headers](https://github.com/IndianOpinion/wp-edge-cache-headers), under the MIT licence, and v0.1.0 was released on 12 November 2026.

It makes the decision once, in PHP, per request, and generates the nginx and Cloudflare configuration that matches it. We wrote it from scratch. It is independent of and not affiliated with any third-party plugin it integrates with.

## The problem

WordPress sends no Cache-Control on a normal anonymous page. It sends a no-cache set for logged-in users, for 404s and for a few core screens, and nothing for the front page, posts, archives, feeds or sitemaps. A CDN that sees no header treats the page as dynamic. Without the header, Cloudflare reports DYNAMIC on every HTML request, so nothing is cached at the edge. A single theme feature that sets a cookie on anonymous article views also makes a template uncacheable at both layers.

The fix is easy to get subtly wrong. Cache one logged-in page publicly and you leak a session. Set the TTL too short and the origin rebuilds pages all day. Let nginx, PHP and the CDN disagree about what is cacheable and the hit ratio quietly collapses.

## What it does

- Sends exactly one Cache-Control on anonymous HTML, with s-maxage, stale-while-revalidate and stale-if-error, and a TTL chosen by template type.

- Sends private, no-store for every bypass condition: logged-in users, listed cookie prefixes, commerce pages, an Authorization header, preview and page-builder arguments, comment moderation, _wpnonce, password-protected posts, non-public statuses, and methods other than GET and HEAD.

- Ships three TTL profiles, quiet, steady and busy, picked from a posts-per-hour figure. wp edge-cache suggest-rate measures it.

- Can send X-Accel-Expires, a bypass signal header, CDN-Cache-Control and Surrogate-Control, each behind a switch.

- Explains any URL from wp-admin or WP-CLI: what header it would get, and why.

- Generates the nginx snippet and the Cloudflare cache rule from the live configuration.

- Offers a filter for every value and list, all prefixed edge_cache_headers_, and an action edge_cache_headers_decided for logging.

## How it works

The decision engine is a pure PHP class with no WordPress calls: request facts in, a header set out. The WordPress layer gathers the facts and applies the result at five points:

- wp_headers: the main decision, merged into the headers core is about to send.

- send_headers: replaces any duplicate Cache-Control and removes the Expires and Pragma that core queued for 404s.

- wp_redirect_status: canonical and plugin redirects are re-decided. 301 and 308 are cacheable, 302, 303 and 307 are private.

- template_include: a late check that only downgrades, for cookies, no-cache headers and status changes that appeared after the main decision.

- rest_pre_serve_request: REST responses.

Every bypass condition is checked before a TTL is chosen. Core's own no-cache calls are recognised and replaced. Anyone else's no-cache is respected: the plugin leaves that header alone and adds a no-store signal for the CDN. Browser max-age stays 0 for HTML, so a reader who logs in never sees an anonymous copy from their own disk.

Settings resolve in order: defaults, network defaults, site settings, constants, filters. To debug one request, rotate a token with wp edge-cache token and send it:

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; ... reasons=debug-token

A request with the token is always private, so it is never cached. The debug header never contains cookie values, user ids, nonces or query values.

## Guard rails

- A filter that throws makes the response private with the reason error. A filter that returns an invalid value is ignored and the default is used.

- The debug header appears only with debug on or a valid token. The token is stored as a hash and compared in constant time, and the constant needs at least 32 characters.

- Search is never cached, because every search URL is unique and expensive.

- EDGE_CACHE_HEADERS_DISABLED turns the plugin off everywhere. Other constants lock their settings, and the settings page shows them read-only.

- Strict mode, which is off by default, buffers output to catch cookies and status changes made while the theme prints.

- Settings and explain forms check capabilities and nonces, and output is escaped.

- The decision filter can turn a private decision public. The README says not to do that for identified visitors.

## What review changed

The reviewer called the engine sound and fixed these in two commits before the merge:

- A plugin calling header('Cache-Control: public, ...') at template_redirect replaced the plugin's header after send_headers, and the late check left it there. The late check now re-applies the plugin's headers when the queued one is no longer its own.

- Core applies the status from the error query variable only after wp_headers, so /?error=500 was decided as a 200 and could go public. The decision now reads it from the request object core passes to the filter.

- X-Accel-Expires: 0 was still sent on private and respect outcomes when its switch was off. It is now absent on every outcome.

- The network settings page showed the current site's overrides, and saving would have copied them into the network defaults. It now shows and saves the network defaults.

- The plugin header carried Network: true, which forced network-only activation. It was removed.

The review also corrected the generated Cloudflare expression, which now parenthesises each negated clause, and it added a trap to the nginx notes: an add_header in the PHP location stops server-level add_header lines from being inherited.

## Limits and what is next

- 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, such as a stray byte before <?php, the plugin 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, and purge plugins can coexist.

- No TTL growth with post age yet.

- The nginx contract does not apply to Apache or LiteSpeed, though the headers still work there. Cloudflare APO uses its own logic and is out of scope.

- Page-cache plugins that serve before WordPress loads skip this plugin, so its headers never appear on those responses.

- The reviewer left one item open. The two any(...) clauses in the generated Cloudflare expression follow the documented form, but the docs have no example using in or ne inside any(). Paste the rule into the dashboard editor once to confirm it is accepted.

Test status: this is v0.1.0, tested on stubs and mocks. At review, 141 tests passed with PHPStan level 8 and phpcs clean, with no live WordPress, nginx or Cloudflare in the loop, and the docs match the generator output byte for byte. CI has not yet run on GitHub, because the token lacked the scope to push it. There are no open issues.

## Install

The package is not on Packagist yet, so first add a Composer vcs repository entry for https://github.com/IndianOpinion/wp-edge-cache-headers.

composer require indianopinion/wp-edge-cache-headers

It needs WordPress 6.4 or later and PHP 8.1 or later, with no Composer at runtime and no build step. Without Composer, clone it into wp-content/plugins/wp-edge-cache-headers and activate it, or copy it to mu-plugins with the one-line loader from the examples.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [wp-edge-cache-headers on GitHub](https://github.com/IndianOpinion/wp-edge-cache-headers)

Canonical: https://indianopinion.org/blog/open-source/wp-edge-cache-headers/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
