Architecture and execution phases

POM Cache has two independent file stores—static HTML and progressive JSON—and several possible delivery layers. Understanding when code runs is essential when extending either store.

The HTML lifecycle

Phase 1: early cache read

When WordPress has WP_CACHE enabled and loads the POM Cache advanced-cache.php drop-in, POM Cache can classify the request and serve an existing HTML file before normal WordPress plugin loading.

This phase is intentionally small. It checks the request method, path, query, bypass cookies, cache constants, and file safety. A successful PHP hit terminates the request with:

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

A normal plugin's add_filter() call has not necessarily run at this point. Hooks that are loaded through the early bootstrap can participate, but ordinary plugin callbacks must not be treated as the sole protection for private content.

Phase 2: WordPress render and cache write

When no early file is served, WordPress loads normally. POM Cache buffers the generated response, classifies the final request and response, and writes an eligible complete representation to index.html.

The visitor receives the normal rendered buffer. POM Cache creates a separate cached copy, applies pom_cache_buffer, appends diagnostic comments, writes a temporary file, and atomically moves it into place.

This phase is where conventional WordPress hooks can reliably influence generation and writing.

Optional Apache delivery

Copied Apache rewrite rules may serve the file before PHP and WordPress execute at all. No PHP callback or diagnostic header can run on such a hit.

The rules are a deployment copy. Turning off a POM Cache setting does not automatically remove or neutralize a previously installed web-server rule. Change the rule itself when disabling direct delivery.

The progressive JSON lifecycle

Progressive JSON has separate master, read-fallback, write, and purge settings.

POM Theme can ask POM Cache for an already stored progressive archive payload through pom_progressive_archive_cached_json. If none is supplied, the theme generates the JSON and announces it through pom_progressive_archive_json_generated; POM Cache stores it only when the generation context says it is cacheable.

An eligible JSON URL can also be served early from the drop-in, or directly by an optional Apache rule. HTML settings do not implicitly enable, clear, or validate the JSON store.

Invalidation flow

Content changes can trigger current-site HTML and JSON clearing when their respective purge settings are enabled. Programmatic helpers can also clear a store directly.

The normal high-level order is:

1. a content or integration event occurs;
2. post and site-deletion filters can veto the relevant purge;
3. POM Cache removes the current site's artifacts;
4. later eligible requests regenerate them;
5. an external CDN must be invalidated independently if it still holds old objects.

HTML and JSON invalidation are separate. A shared pom_cache_should_delete_site_cache gate is consulted by both high-level site-clear helpers, while JSON has an additional JSON-specific gate.

CDN and compression boundary

POM Cache controls origin artifacts. A CDN controls its own object cache, compression negotiation, and edge lifetime. It can continue returning an object after the origin file is deleted.

Treat the complete delivery path as:

WordPress source → POM Cache artifact → PHP or Apache origin response → CDN → browser

Debug and invalidate from left to right.

Design consequences for extensions

• A late filter can prevent future writes but may not block an existing early hit.
• When a representation becomes private, clear previously generated files as part of the rollout.
• Never make a cache key represent multiple outputs that vary by user, authorization, cart, nonce, or secret.
• Use independent HTML and JSON invalidation when only one representation changes.
• Do not run licensing, remote APIs, database-heavy work, or user-specific logic on the early hit path.
• Test PHP delivery before optional Apache delivery, and origin delivery before the CDN.