Serve JSON cache files early from PHP

PHP early static serving is the default fast path for an existing progressive JSON file. It runs through the POM Cache advanced-cache.php drop-in before the normal WordPress request finishes.

It is the recommended first delivery layer because it is faster than a WordPress fallback while remaining controlled by the plugin settings.

Enable the layer

1. Open Settings → POM Cache → General.
2. Find Progressive JSON runtime.
3. Set Progressive JSON cache to Enabled.
4. Set PHP early static serving to Enabled.
5. Keep JSON writes enabled while building the cache.
6. Save.

The WordPress configuration must also load the POM Cache drop-in. Review POM Cache → Advanced → WordPress configuration if no early hit is possible.

Static HTML Caching may remain disabled. The early bootstrap checks progressive JSON independently before it decides whether to handle HTML.

Requests eligible for early serving

POM Cache accepts:

• GET;
• HEAD;
• a supported /pom-json/...json route;
• the compatible /wp-json/pom/v1/progressive-archive/...json route;
• either route with one recognized locale-style prefix;
• an empty query string.

It then checks that the file exists, is readable, is non-empty, and does not exceed Maximum JSON file size.

Early delivery is bypassed when the request carries a recognized private-session cookie, including WordPress authentication or password cookies and common WooCommerce session/cart cookies. It is also bypassed when the request has been marked with DONOTCACHEPAGE.

Headers returned by PHP

A hit returns status 200 with:

Content-Type: application/json; charset=UTF-8
Cache-Control: public, max-age=30, s-maxage=30, must-revalidate
X-POM-Cache: Served static JSON cache from PHP; phase=early
Vary: Accept-Encoding
Content-Length: <file size>

The Cache-Control line uses your current JSON Cache-Control header setting; the value above is the default.

For a HEAD request, the same metadata is returned without reading the body into the response.

Vary: Accept-Encoding tells a downstream cache that content-encoding variants may differ. POM Cache itself does not Brotli- or Gzip-compress the file; that remains the responsibility of the web server or CDN.

Why this path is safer than a blind file mapping

The PHP layer applies the current master and child switches on every request. It also uses the current maximum size and bypass rules. Disabling PHP early static serving takes effect without editing server configuration.

By contrast, a copied Apache rule continues to exist outside WordPress until it is removed. PHP early serving is therefore useful as:

• the initial production rollout;
• a fallback behind direct Apache delivery;
• the primary path on hosts where .htaccess cannot be changed;
• a diagnostic layer while validating stored files and headers.

Verify an early hit

1. Clear the progressive JSON cache.

2. Request one clean progressive batch in a private browser window.

3. Confirm Progressive JSON Cache Contents increases.

4. Repeat the exact URL without a query string.

5. Inspect the headers for:

   X-POM-Cache: Served static JSON cache from PHP; phase=early

6. Send a HEAD request and confirm it returns headers without a body.

7. Repeat while logged in and confirm the early header is absent.

If an active CDN answers the request, perform the check against the origin through an approved CDN-bypass method. Otherwise you may be observing an edge hit rather than POM Cache.

Isolate a problem

If the file exists but the early header never appears:

1. Make sure optional Apache delivery is not already winning;
2. Verify Progressive JSON cache and PHP early static serving are enabled;
3. Check the drop-in status under WordPress configuration;
4. Remove query parameters from the test URL;
5. Use a logged-out, empty-cart browser session;
6. Compare the file size with Maximum JSON file size;
7. Confirm the JSON is valid and readable by PHP;
8. Enable WordPress read fallback and check whether the later router reports a hit.

A WordPress fallback hit with no early hit usually points to the drop-in, request eligibility, or early file lookup—not to JSON generation.

Continue with Use the WordPress JSON fallback to understand that diagnostic distinction.