cHash para TYPO3

La mayoría de los errores “Page not found” en TYPO3 son problemas de cHash

Un redactor crea una noticia con paginación, la página funciona. Un visitante hace clic en la página 2, ve “Page not found”. El desarrollador revisa el routing, la configuración de la página, el .htaccess. Todo correcto. El problema está más profundo: el mecanismo cHash de TYPO3 no esperaba el parámetro URL de la paginación y rechaza la entrega. Un problema de 5 minutos si sabes dónde buscar, un problema de 2 días si no.

cHash (Cache Hash) es el mecanismo de TYPO3 para proteger la caché de páginas. Calcula un hash de todos los parámetros URL y lo compara con la entrada de caché almacenada. Si aparece un parámetro desconocido que TYPO3 no espera, la página no se entrega. Esto protege contra cache poisoning, pero causa problemas con casi cada nueva extensión o cada filtro personalizado.

Escenarios de uso habituales

Búsqueda facetada en catálogos de productos. Un catálogo de productos con 6 criterios de filtrado (categoría, precio, color, material, disponibilidad, valoración) genera parámetros URL como &tx_catalog[color]=red&tx_catalog[price]=100-200. Sin configuración cHash, TYPO3 muestra “Page not found” con cada combinación de filtros. La configuración cHash debe conocer cada uno de estos parámetros, ya sea como “required” (influye en la clave de caché) o como “excluded” (se ignora y no se hashea).

Paginación en listas de noticias y eventos. EXT:news y EXT:sf_event_mgt usan sus propios parámetros URL para números de página. Estos parámetros deben estar en la configuración cHash para que la página 2 obtenga su propia entrada de caché. Si falta la configuración, se entrega siempre la página 1 desde la caché (cache pollution) o la paginación falla con 404.

Parámetros de tracking y etiquetas UTM. Las campañas de marketing añaden parámetros UTM a las URLs: ?utm_source=newsletter&utm_medium=email. Sin excluir estos parámetros, cada enlace de campaña crea una nueva entrada de caché. En un sitio web con 500 páginas y 10 campañas, en lugar de 500 surgen repentinamente 5.000 entradas de caché que sobrecargan el servidor. Los parámetros UTM pertenecen a la lista de exclusión.

Arquitectura técnica

El cálculo del cHash se produce en la clase Core de TYPO3 CacheHashCalculator. El algoritmo toma todos los parámetros URL, los ordena alfabéticamente, los serializa y calcula un hash MD5. Este hash se añade como parámetro cHash a la URL. Al acceder a la página, TYPO3 verifica si el cHash proporcionado coincide con el calculado.

La configuración se realiza en $GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash'] con cuatro listas:

cachedParametersWhiteList: parámetros que entran en el hash y crean entradas de caché propias. Típico: parámetros de plugins (tx_news_pi1, tx_solr).

excludedParameters: parámetros que se ignoran completamente. Típico: parámetros de tracking (utm_source, utm_medium, utm_campaign, gclid, fbclid).

requireCacheHashPresenceParameters: parámetros que requieren obligatoriamente un cHash. Si este parámetro aparece en la URL sin cHash, TYPO3 muestra un error 404.

Desde TYPO3 v12, la configuración cHash también se puede controlar a través de la Site Configuration (config.yaml), lo que simplifica la gestión en configuraciones multi-sitio.

Problemas frecuentes y soluciones

“Page not found” tras instalar una extensión. Las nuevas extensiones traen sus propios parámetros URL. Si no están en la configuración cHash, TYPO3 bloquea la página. Solución: verificar la documentación de la extensión (las buenas extensiones incluyen configuración cHash en ext_localconf.php). Si no: añadir manualmente los parámetros a cachedParametersWhiteList o excludedParameters.

Cache pollution por parámetros no controlados. Bots y crawlers de spam añaden parámetros aleatorios a las URLs. Sin protección, cada una de estas llamadas crea una entrada de caché. El caché crece a millones de entradas, la base de datos se ralentiza. Solución: establecer excludeAllEmptyParameters = true y aceptar solo parámetros explícitamente conocidos en la WhiteList.

Errores cHash difíciles de depurar. TYPO3 solo muestra “Page not found”, no por qué. En modo producción no hay mensaje de error que apunte al cHash. Solución: establecer temporalmente $GLOBALS['TYPO3_CONF_VARS']['FE']['pageNotFoundOnCHashError'] = false en LocalConfiguration.php. Entonces TYPO3 muestra la página a pesar del error cHash y registra el error.

Migración y compatibilidad de versiones

cHash es funcionalidad del Core, no una extensión, y existe desde TYPO3 v4. La configuración ha cambiado a lo largo de las versiones: en TYPO3 v8 y anteriores se controlaba mediante TypoScript, desde v9 mediante arrays PHP en LocalConfiguration, desde v12 adicionalmente mediante Site Configuration.

En la migración de TYPO3 v9/v10 a v12/v13, las configuraciones cHash existentes deben revisarse. Los nombres de parámetros de las extensiones pueden haber cambiado. El camino más seguro: tras la actualización, probar sistemáticamente todas las páginas con parámetros (paginación, filtros, búsqueda) y comprobar el log de errores de TYPO3 en busca de entradas cHash.

TYPO3 v13 endurece aún más la comprobación cHash: los parámetros desconocidos provocan un 404 por defecto, el modo debug debe activarse explícitamente. Gosign verifica la configuración cHash como parte del proceso de aseguramiento de calidad en cada proyecto de actualización TYPO3.