cHash para TYPO3

A maioria dos erros “Page not found” no TYPO3 são problemas de cHash

Um editor cria uma notícia com paginação, a página funciona. Um visitante clica na página 2, vê “Page not found”. O desenvolvedor verifica o roteamento, a configuração da página, o .htaccess. Tudo correto. O problema é mais profundo: o mecanismo cHash do TYPO3 não esperava o parâmetro URL da paginação e recusa a entrega. Um problema de 5 minutos quando se sabe onde procurar, um problema de 2 dias quando não.

cHash (Cache Hash) é o mecanismo do TYPO3 para proteger o cache de páginas. Ele calcula um hash de todos os parâmetros URL e compara com a entrada de cache armazenada. Quando aparece um parâmetro desconhecido que o TYPO3 não espera, a página não é entregue. Isso protege contra cache poisoning, mas causa problemas com quase toda nova extensão ou filtro customizado.

Cenários típicos de uso

Busca com filtros e facetas em catálogos de produtos. Um catálogo de produtos com 6 critérios de filtro (categoria, preço, cor, material, disponibilidade, avaliação) gera parâmetros URL como &tx_catalog[color]=red&tx_catalog[price]=100-200. Sem configuração cHash, o TYPO3 mostra “Page not found” para cada combinação de filtro. A configuração cHash deve conhecer cada um desses parâmetros, seja como “required” (influencia a chave de cache) ou como “excluded” (é ignorado e não é hasheado).

Paginação em listas de news e eventos. EXT:news e EXT:sf_event_mgt usam parâmetros URL próprios para números de página. Esses parâmetros devem estar na configuração cHash para que a página 2 receba sua própria entrada de cache. Se a configuração estiver ausente, ou sempre a página 1 é entregue do cache (cache pollution) ou a paginação falha com 404.

Parâmetros de tracking e tags UTM. Campanhas de marketing adicionam parâmetros UTM às URLs: ?utm_source=newsletter&utm_medium=email. Sem exclusão desses parâmetros, cada link de campanha cria uma nova entrada de cache. Em um site com 500 páginas e 10 campanhas, surgem de repente 5.000 entradas de cache em vez de 500, sobrecarregando o servidor e desacelerando o cache warmup. Parâmetros UTM pertencem à lista de exclusão.

Arquitetura técnica

O cálculo de cHash ocorre na classe Core CacheHashCalculator do TYPO3. O algoritmo pega todos os parâmetros URL, os ordena alfabeticamente, serializa e calcula um hash MD5. Esse hash é adicionado à URL como parâmetro cHash. Ao acessar a página, o TYPO3 verifica se o cHash fornecido corresponde ao calculado.

A configuração é feita em $GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash'] com quatro listas:

cachedParametersWhiteList: Parâmetros que entram no hash e criam entradas de cache próprias. Típico: parâmetros de plugin (tx_news_pi1, tx_solr).

excludedParameters: Parâmetros completamente ignorados. Típico: parâmetros de tracking (utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid).

requireCacheHashPresenceParameters: Parâmetros que obrigatoriamente requerem um cHash. Se esse parâmetro estiver na URL sem cHash, o TYPO3 mostra um erro 404. Esse é o modo mais restritivo.

excludedParametersIfEmpty: Parâmetros que só são ignorados quando estão vazios.

Desde TYPO3 v12, a configuração cHash também pode ser controlada via Site Configuration (config.yaml), o que simplifica a gestão em setups multi-site.

Problemas frequentes e soluções

“Page not found” após instalação de extensão. Novas extensões trazem parâmetros URL próprios. Se não estiverem na configuração cHash, o TYPO3 bloqueia a página. Solução: verificar a documentação da extensão (boas extensões incluem configuração cHash em ext_localconf.php). Caso contrário: adicionar os parâmetros manualmente na cachedParametersWhiteList ou excludedParameters. No Install Tool do TYPO3 em “Presets”, o modo debug de cHash oferece auxílio.

Cache pollution por parâmetros descontrolados. Bots e crawlers de spam adicionam parâmetros aleatórios às URLs. Sem proteção, cada uma dessas chamadas cria uma entrada de cache. O cache cresce para milhões de entradas, o banco de dados fica lento. Solução: definir excludeAllEmptyParameters = true e só adicionar parâmetros explicitamente conhecidos na WhiteList. Adicionalmente, ajustar o garbage collector do cache para intervalos mais curtos (padrão: 86.400 segundos = 24 horas).

Erros cHash difíceis de debugar. O TYPO3 mostra apenas “Page not found”, sem dizer por quê. No modo de produção não há mensagem de erro que indique cHash. Solução: em LocalConfiguration.php definir temporariamente $GLOBALS['TYPO3_CONF_VARS']['FE']['pageNotFoundOnCHashError'] = false. Assim o TYPO3 mostra a página apesar do erro cHash e registra o erro. Após o diagnóstico, voltar para true.

Migração e compatibilidade de versões

cHash é funcionalidade Core, não uma extensão, e existe desde TYPO3 v4. A configuração mudou ao longo das versões: no TYPO3 v8 e anterior era controlada via TypoScript, a partir da v9 via arrays PHP na LocalConfiguration, a partir da v12 adicionalmente via Site Configuration.

Na migração de TYPO3 v9/v10 para v12/v13, configurações cHash existentes devem ser verificadas. Os nomes de parâmetros das extensões podem ter mudado (p.ex. alterações de namespace de plugin Extbase). O caminho mais seguro: após o upgrade, testar sistematicamente todas as páginas com parâmetros (paginação, filtros, busca) e verificar o Error Log do TYPO3 para entradas cHash.

TYPO3 v13 endurece a verificação cHash ainda mais: parâmetros desconhecidos levam por padrão a um 404, o modo debug deve ser explicitamente ativado. A Gosign verifica em todo projeto de upgrade TYPO3 a configuração cHash como parte do processo de garantia de qualidade.