Control static cache eligibility

POM Cache rejects unsafe requests before serving or writing static HTML. Extensions should add narrower exclusions, not override the existing protections.

Exclude a cached HTML read

Use pom_cache_can_serve_cached_file to veto an existing PHP-served file:

add_filter(
    'pom_cache_can_serve_cached_file',
    static function ( $can_serve, $file, $context ) {
        unset( $file );

        if ( ! $can_serve ) {
            return false;
        }

        $request_uri = isset( $context['request_uri'] )
            ? (string) $context['request_uri']
            : '';

        if ( str_starts_with( $request_uri, '/account-preview/' ) ) {
            return false;
        }

        return true;
    },
    10,
    3
);

The callback first preserves an existing rejection. Never return true simply because your own exclusion does not match; doing so could re-enable a read rejected because of a bypass cookie or DONOTCACHEPAGE.

Known context keys are:

• phase;
• file;
• request_uri;
• request_method;
• has_cache_bypass_cookie;
• donotcachepage_defined;
• is_user_logged_in.

Treat the array as extensible and check every key before reading it.

Early-phase limitation

The default read decision is true only for the early phase when there is no bypass cookie and DONOTCACHEPAGE is not defined. That decision can occur through advanced-cache.php before conventional plugins have registered their filters.

Consequently, a normal plugin callback is not a complete privacy boundary for an already cached page. When adding private behavior:

1. stop or constrain the feature's future HTML writes;
2. disable copied Apache direct rules for the affected path;
3. clear existing HTML files;
4. invalidate external edge caches;
5. test the clean and authenticated request paths.

Use application design and cache configuration—not only a late read filter—to keep private routes out of the cache.

Exclude generation with DONOTCACHEPAGE

When your code knows during a normal WordPress request that the response must remain dynamic, define the standard constant before POM Cache evaluates the completed buffer:

add_action(
    'template_redirect',
    static function () {
        if ( is_page( 'account-preview' ) && ! defined( 'DONOTCACHEPAGE' ) ) {
            define( 'DONOTCACHEPAGE', true );
        }
    },
    1
);

This prevents the current WordPress render from being written. It does not remove an older file and cannot intercept Apache delivery or an early response that has already finished.

Unknown-page behavior

pom_cache_only_cache_known_pages defaults to a truthy value. It prevents POM Cache from writing output that WordPress could not classify as a known page.

Changing it to false broadens eligibility:

add_filter( 'pom_cache_only_cache_known_pages', '__return_false' );

This is intentionally not recommended as a generic fix for “page not cached.” It can admit custom endpoints, error-like responses, or output whose freshness contract is unknown. Prefer registering the route correctly in WordPress and testing its public behavior.

Verification matrix

For every eligibility customization, test:

• anonymous miss and subsequent hit;
• logged-in request;
• every session or commerce cookie used by the feature;
• meaningful query strings;
• POST, PUT, and DELETE;
• error and redirect paths;
• existing file after the feature becomes private;
• PHP, Apache, and CDN delivery separately.

An extension is correct only if it controls both future generation and any artifacts produced before the rule existed.