cHash dla TYPO3

Większość błędów “Page not found” w TYPO3 to problemy z cHash

Redaktor tworzy wiadomość z paginacją, strona działa. Odwiedzający klika na stronę 2 i widzi “Page not found”. Developer sprawdza routing, konfigurację stron, .htaccess. Wszystko poprawne. Problem leży głębiej: mechanizm cHash TYPO3 nie oczekiwał parametru URL paginacji i odmawia dostarczenia strony. Problem na 5 minut, jeśli wiesz gdzie szukać - problem na 2 dni, jeśli nie.

cHash (Cache Hash) to mechanizm TYPO3 zabezpieczający cache stron. Oblicza hash ze wszystkich parametrów URL i porównuje go z zapisanym wpisem cache. Gdy pojawia się nieznany parametr, którego TYPO3 nie oczekuje, strona nie jest dostarczana. Chroni to przed cache poisoning, ale powoduje problemy przy prawie każdym nowym rozszerzeniu lub niestandardowym filtrze.

Typowe scenariusze zastosowania

Filtry i wyszukiwanie fasetowe w katalogach produktów. Katalog produktów z 6 kryteriami filtrowania (kategoria, cena, kolor, materiał, dostępność, ocena) generuje parametry URL jak &tx_catalog[color]=red&tx_catalog[price]=100-200. Bez konfiguracji cHash TYPO3 pokazuje przy każdej kombinacji filtrów “Page not found”. Konfiguracja cHash musi znać każdy z tych parametrów - albo jako “required” (wpływa na klucz cache), albo jako “excluded” (jest ignorowany i nie hashowany).

Paginacja w listach aktualności i wydarzeń. EXT:news i EXT:sf_event_mgt używają własnych parametrów URL dla numerów stron (&tx_news_pi1[@widget_0][currentPage]=2). Te parametry muszą znajdować się w konfiguracji cHash, aby strona 2 otrzymała własny wpis cache. Brak konfiguracji powoduje albo dostarczanie zawsze strony 1 z cache (zanieczyszczenie cache), albo błąd 404 paginacji.

Parametry śledzenia i tagi UTM. Kampanie marketingowe dodają parametry UTM do URL: ?utm_source=newsletter&utm_medium=email. Bez wykluczenia tych parametrów każdy link kampanii tworzy nowy wpis cache. Przy stronie z 500 stronami i 10 kampaniami zamiast 500 powstaje nagle 5000 wpisów cache, obciążających serwer i spowalniających rozgrzewanie cache. Parametry UTM należy umieścić na liście wykluczeń.

Architektura techniczna

Obliczanie cHash odbywa się w klasie rdzeniowej TYPO3 CacheHashCalculator. Algorytm pobiera wszystkie parametry URL, sortuje je alfabetycznie, serializuje i oblicza hash MD5. Ten hash jest dołączany do URL jako parametr cHash. Przy wywoływaniu strony TYPO3 sprawdza, czy dostarczony cHash zgadza się z obliczonym.

Konfiguracja odbywa się w $GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash'] z czterema listami:

cachedParametersWhiteList: parametry włączane do hasha, tworzące własne wpisy cache. Typowe: parametry pluginów (tx_news_pi1, tx_solr).

excludedParameters: parametry całkowicie ignorowane. Typowe: parametry śledzenia (utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid).

requireCacheHashPresenceParameters: parametry wymagające obowiązkowo cHash. Gdy taki parametr pojawia się w URL bez cHash, TYPO3 wyświetla błąd 404. To najbardziej restrykcyjny tryb.

excludedParametersIfEmpty: parametry ignorowane tylko gdy są puste.

Od TYPO3 v12 konfigurację cHash można również sterować przez Site Configuration (config.yaml), co upraszcza zarządzanie w konfiguracjach Multi-Site.

Częste problemy i rozwiązania

“Page not found” po instalacji rozszerzenia. Nowe rozszerzenia wprowadzają własne parametry URL. Gdy nie ma ich w konfiguracji cHash, TYPO3 blokuje stronę. Rozwiązanie: sprawdzenie dokumentacji rozszerzenia (dobre rozszerzenia dostarczają konfigurację cHash w ext_localconf.php). Jeśli nie - ręczne dodanie parametrów do cachedParametersWhiteList lub excludedParameters. W narzędziu Install Tool TYPO3 w sekcji “Presets” tryb debugowania cHash oferuje pomoc.

Zanieczyszczenie cache przez niekontrolowane parametry. Boty i crawlery spamowe dołączają losowe parametry do URL. Bez ochrony każde takie wywołanie tworzy wpis cache. Cache rośnie do milionów wpisów, baza danych staje się wolna. Rozwiązanie: ustawienie excludeAllEmptyParameters = true i dodanie do WhiteList tylko jawnie znanych parametrów. Dodatkowo skrócenie interwałów garbage collectora cache (domyślnie: 86 400 sekund = 24 godziny).

Błędy cHash trudne do debugowania. TYPO3 pokazuje tylko “Page not found”, nie dlaczego. W trybie produkcyjnym nie ma komunikatu błędu wskazującego na cHash. Rozwiązanie: tymczasowe ustawienie w LocalConfiguration.php $GLOBALS['TYPO3_CONF_VARS']['FE']['pageNotFoundOnCHashError'] = false. Wtedy TYPO3 wyświetla stronę mimo błędu cHash i loguje błąd. Po diagnozie ponowne ustawienie na true.

Migracja i kompatybilność wersji

cHash to funkcjonalność rdzeniowa, nie rozszerzenie, i istnieje od TYPO3 v4. Konfiguracja zmieniała się w kolejnych wersjach: w TYPO3 v8 i wcześniejszych sterowana przez TypoScript, od v9 przez tablice PHP w LocalConfiguration, od v12 dodatkowo przez Site Configuration.

Przy migracji z TYPO3 v9/v10 na v12/v13 istniejące konfiguracje cHash muszą być sprawdzone. Nazwy parametrów rozszerzeń mogły się zmienić (np. zmiany namespace pluginów Extbase). Najbezpieczniejsza droga: po aktualizacji systematyczne testowanie wszystkich stron z parametrami (paginacja, filtry, wyszukiwanie) i sprawdzenie TYPO3 Error Log pod kątem wpisów cHash.

TYPO3 v13 dodatkowo zaostrza sprawdzanie cHash: nieznane parametry domyślnie prowadzą do 404, tryb debugowania musi być jawnie aktywowany. Gosign przy każdym projekcie aktualizacji TYPO3 sprawdza konfigurację cHash jako część procesu zapewnienia jakości.