Understand cache-directory and filename filters

POM Cache exposes path filters for specialized deployments, but they are not interchangeable with a filename configuration API. A path change must remain consistent across early reads, WordPress writes, deletion, statistics, Apache rules, and multisite isolation.

Prefer the Cache Location setting

For ordinary deployments, configure storage through Settings → POM Cache → Advanced → Storage. It updates the generated early settings that POM Cache expects.

A WordPress filter registered by a normal plugin may not exist during the earliest drop-in phase. Using a late path filter can therefore make WordPress write to one location while the early reader looks in another.

pom_cache_cache_dir

This filter receives the absolute current-site HTML cache base path:

add_filter(
    'pom_cache_cache_dir',
    static function ( $path ) {
        return $path;
    }
);

If you return a different path, it must be absolute, dedicated to cache data, writable by PHP, and safely isolated by site. Review every web-server rule and operational tool before deployment.

Do not derive it from unchecked host, query, cookie, or request input.

pom_cache_dir

This filter receives the host-and-request fragment before it is combined with the cache root:

add_filter(
    'pom_cache_dir',
    static function ( $fragment ) {
        return $fragment;
    }
);

Changing the fragment changes the mapping between a URL and its HTML directory. It is easy to create collisions between hosts, languages, or paths. It is also easy to strand old artifacts.

Use this hook only when your integration controls:

• the early bootstrap that registers the filter;
• the WordPress write path;
• Apache or other direct-server rules;
• cache-status reporting;
• invalidation and deletion;
• migration from the old mapping.

pom_cache_filenames does not rename the artifact

The current POM Cache HTML reader and writer use:

index.html

pom_cache_filenames filters the list returned by pom_cache_get_cache_filenames():

add_filter(
    'pom_cache_filenames',
    static function ( $filenames ) {
        $filenames[] = 'legacy-index.html';

        return $filenames;
    }
);

This can extend code that explicitly calls that listing helper. It does not make the canonical writer create legacy-index.html, and it does not make the current early reader serve that file. Do not present it as filename customization.

Protected pruning directories

pom_cache_protected_directories extends the absolute paths that the HTML pruning routine must not remove:

add_filter(
    'pom_cache_protected_directories',
    static function ( $directories ) {
        $directories[] = WP_CONTENT_DIR . '/cache/shared-protected';

        return array_values( array_unique( $directories ) );
    }
);

Add only reviewed absolute directories. This filter prevents removal; it does not make an external directory part of the supported cache layout.

Deployment checklist

Before shipping a path customization:

1. prove the mapping for every site and host;
2. prove that no two public representations collide;
3. confirm early and WordPress phases use the same path;
4. regenerate copied Apache rules;
5. confirm statistics and manual clearing target that location;
6. back up and migrate or retire the old cache tree;
7. test symlink, permission, and path-containment behavior;
8. validate origin and CDN invalidation.

If you cannot control every item, use the normal storage setting and keep index.html.