Comprender los filtros de directorio de caché y de nombre de archivo

POM Cache expone filtros de ruta para despliegues especializados, pero no son intercambiables con una API de configuración de nombres de archivo. Un cambio de ruta debe mantenerse coherente en las lecturas tempranas, las escrituras de WordPress, la eliminación, las estadísticas, las reglas de Apache y el aislamiento multisitio.

Prefiere el ajuste Cache Location

En despliegues ordinarios, configura el almacenamiento a través de Settings → POM Cache → Advanced → Storage. Actualiza los ajustes tempranos generados que POM Cache espera.

Un filtro de WordPress registrado por un plugin normal puede no existir durante la fase más temprana del drop-in. Por tanto, usar un filtro de ruta tardío puede hacer que WordPress escriba en una ubicación mientras el lector temprano busca en otra.

pom_cache_cache_dir

Este filtro recibe la ruta base absoluta de caché HTML del sitio actual:

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

Si devuelves una ruta distinta, debe ser absoluta, dedicada a datos de caché, escribible por PHP y aislada de forma segura por sitio. Revisa cada regla del servidor web y cada herramienta operativa antes del despliegue.

No la derives de entradas de host, consulta, cookie o solicitud sin comprobar.

pom_cache_dir

Este filtro recibe el fragmento de host y solicitud antes de que se combine con la raíz de caché:

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

Cambiar el fragmento cambia el mapeo entre una URL y su directorio HTML. Es fácil crear colisiones entre hosts, idiomas o rutas. También es fácil dejar abandonados artefactos antiguos.

Usa este hook solo cuando tu integración controle:

• el bootstrap temprano que registra el filtro;
• la ruta de escritura de WordPress;
• Apache u otras reglas directas del servidor;
• los informes de estado de la caché;
• la invalidación y la eliminación;
• la migración desde el mapeo antiguo.

pom_cache_filenames no renombra el artefacto

El lector y escritor HTML ordinarios de POM Cache usan:

index.html

Las políticas explícitas de pom_cache_query_variant usan artefactos HTML separados para las combinaciones de consulta aprobadas. La lista de nombres de archivo incluye esas entradas para que al limpiar una URL también se limpien sus variantes. Usa ese hook de política para registrar variantes; no intentes crearlas sustituyendo los filtros de directorio o de nombre de archivo.

pom_cache_filenames filtra la lista devuelta por pom_cache_get_cache_filenames():

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

        return $filenames;
    }
);

Esto puede ampliar código que llame explícitamente a ese helper de listado. No hace que el escritor canónico cree legacy-index.html, y no hace que el lector temprano actual sirva ese archivo. No lo presentes como personalización de nombres de archivo.

Directorios de poda protegidos

pom_cache_protected_directories amplía las rutas absolutas que la rutina de poda de HTML no debe eliminar:

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

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

Añade solo directorios absolutos revisados. Este filtro impide la eliminación; no convierte un directorio externo en parte del diseño de caché admitido.

Lista de comprobación para el despliegue

Antes de publicar una personalización de ruta:

1. comprueba el mapeo de cada sitio y host;
2. comprueba que no colisionen dos representaciones públicas;
3. confirma que las fases temprana y de WordPress usan la misma ruta;
4. regenera las reglas de Apache copiadas;
5. confirma que las estadísticas y la limpieza manual apuntan a esa ubicación;
6. haz una copia de seguridad y migra o retira el árbol de caché antiguo;
7. prueba el comportamiento de enlaces simbólicos, permisos y contención de rutas;
8. valida la invalidación de origen y CDN.

Si no puedes controlar cada elemento, usa el ajuste de almacenamiento normal y mantén index.html.