How POM Cache handles a page request

One page view can pass through several independent decision points. Understanding their order prevents a common mistake: looking for a WordPress header on a response that Apache or a CDN already served.

The sequence below describes the static HTML path for a typical public GET or HEAD request.

1. An upstream cache may answer first

If a CDN is configured, it evaluates its own cache key, cookies, query-string policy, and expiry rules. An edge hit ends the request before the origin sees it.

POM Cache cannot create, purge, or diagnose that edge entry by itself. When checking origin behavior, use the deployment’s approved origin-testing method or invalidate the edge copy first.

2. Apache can look for the static file

With the recommended rewrite block installed, Apache checks the request before the standard WordPress rewrite. The supplied rule is deliberately narrow: it expects a clean public request, a trailing-slash URL, an empty query string, no listed bypass cookie, and an existing index.html at the calculated host-and-path location.

When every condition matches, Apache sends the file directly. PHP and WordPress do not start, so this is the least expensive origin path.

Apache delivery does not add the PHP-specific X-POM-Cache header. The unchanged cache-generation comment or server-level observation is therefore better evidence.

3. WordPress can load the early drop-in

If Apache did not answer, WordPress core checks WP_CACHE. When it is true, WordPress loads wp-content/advanced-cache.php before the normal plugin bootstrap.

The POM Cache drop-in uses POM_CACHE_HOME to load the early runtime. That runtime:

• loads the effective site settings;
• rejects backend, write, Customizer, query-state, and bypass-cookie requests;
• maps the current host and normalized path to an index.html;
• confirms that the resolved file stays inside the configured cache directory;
• serves a valid hit and stops the request.

A PHP early hit includes:

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

For HEAD, POM Cache sends the status and headers without the file body.

4. WordPress renders a miss or bypass

If no layer has served a file, WordPress continues normally. A theme template, block, shortcode, or plugin may still produce a perfectly valid response even though it is not cacheable.

During this phase POM Cache records the kind of page and the final response status. It also starts an output buffer only when the HTML runtime is enabled and the request is not already excluded.

This distinction matters:

• Miss: no reusable file was found for an otherwise eligible request.
• Bypass: policy says the request must not read or write the shared file.

Both reach WordPress, but only the first is expected to populate the cache.

5. The complete response is evaluated

At the end of rendering, POM Cache checks the actual output. It does not store an empty buffer, a fatal response, a normal 404, a redirect, a REST/feed/robots response, a non-HTML representation, or a document without a recognized closing marker.

It also honours DONOTCACHEPAGE, so another component can declare a page unsuitable for shared storage.

If the checks fail, the visitor still receives the WordPress response. No index.html is created.

6. An eligible file is written atomically

For a cacheable response, POM Cache:

1. builds the directory from the current request host and URL path;
2. resolves and validates that directory below Cache Location;
3. creates a uniquely named temporary file;
4. writes the complete HTML plus cache-generation comments;
5. rejects an empty temporary file;
6. renames the file to index.html.

The rename avoids exposing a half-written page to another request. The first visitor receives the original rendered buffer; subsequent visitors can receive the stored version.

7. A late delivery hook remains available

After WordPress knows the current user and queried object, POM Cache performs a late lookup. It does not serve from that point by default. Developers can opt into a carefully constrained late policy through the documented eligibility filter.

This capability is not a reason to cache private views. Its purpose is to let an integration make a decision that was impossible before WordPress loaded.

Read the outcome correctly

A request is healthy when its result matches the intended policy:

• public repeat view → origin or edge hit;
• first public view after a purge → WordPress render followed by a write;
• logged-in, cart, preview, query, or non-HTML request → bypass;
• incomplete or error response → returned but not stored.

Use Understand cache hits and misses to verify which outcome occurred, or Understand cache generation after WordPress renders for the final-response checks.