k3n_dvemoji dla TYPO3: Wsparcie Emoji i migracja UTF-8mb4

Emoji jako znaki zapytania to nie problem wyświetlania, lecz błąd konfiguracji bazy danych

Gdy w backendzie TYPO3 redaktor wpisuje emoji, a w frontendzie zamiast tego pojawia się znak zapytania lub puste pole, problem nie leży w przeglądarce ani w TYPO3. Leży w bazie danych MySQL lub MariaDB skonfigurowanej z zestawem znaków utf8 zamiast utf8mb4. Różnica: utf8 zapisuje maksymalnie 3 bajty na znak, emoji potrzebują 4 bajtów. k3n_dvemoji to rozszerzenie TYPO3 poświęcone temu problemowi, które nie jest opublikowane ani w TER, ani na Packagist, ani na GitHubie; nie da się więc sprawdzić, jak dokładnie go rozwiązuje. Od TYPO3 v9.5 instalator sam ustawia jednak utf8mb4 w nowych instalacjach, dzięki czemu przestawienie jest potrzebne tylko przy starszych lub źle skonfigurowanych instalacjach.

Administratorzy TYPO3 i agencje opiekujące się starszymi instalacjami potrzebują więc jednocześnie diagnozy i naprawy: odnalezienia tabel z błędnym zestawem znaków i ich konwersji, co ręcznie jest procesem podatnym na błędy.

Typowe scenariusze zastosowań dotyczą starszych instalacji, migracji i treści międzynarodowych

Najczęstszy scenariusz to instalacja TYPO3 v8 lub v9 działająca od lat, której baza danych jest nadal skonfigurowana na utf8 (nie utf8mb4). Szacunkowo 30% wszystkich instalacji TYPO3 założonych przed 2018 ma ten problem, ponieważ rutyna instalacyjna wówczas ustawiała utf8 jako domyślny. Dopóki redaktorzy używają tylko znaków łacińskich, nie rzuca się to w oczy. Gdy tylko na stronie zostanie osadzony post social media z emoji lub redaktor wstawi emoji w nagłówek, wyświetlanie się łamie. Rozwiązaniem jest konwersja dotkniętych tabel i kolumn na utf8mb4.

Drugi scenariusz: migracje bazy danych między serwerami. Przy przeprowadzaniu bazy danych TYPO3 ze starego serwera na nowy zestaw znaków może zostać utracony przez błędne polecenie mysqldump. Dump z —default-character-set=utf8 zamiast utf8mb4 obcina wszystkie znaki 4-bajtowe. Wtedy trzeba później skorygować zestaw znaków i import.

Trzeci scenariusz: międzynarodowe strony z językami azjatyckimi. Popularne znaki chińskie, japońskie i koreańskie zajmują w UTF-8 trzy bajty, ale rzadkie i historyczne ideogramy od CJK Extension B wzwyż cztery. Bez utf8mb4 tych znaków nie da się zapisać i są wyświetlane okaleczone. Również symbole matematyczne, nuty i różne znaki specjalne z obszaru Unicode powyżej U+FFFF są dotknięte, co jest istotne dla stron uczelni i portali naukowych.

Architektura techniczna analizuje i konwertuje tabele bazy danych na poziomie kolumny

Przestawienie odbywa się na dwóch poziomach: analizy i konwersji. Podczas analizy skanowane są wszystkie tabele TYPO3 i sprawdzany jest zestaw znaków każdej kolumny. Wynikiem jest raport pokazujący, które tabele i kolumny nadal są na utf8 (3 bajty) zamiast utf8mb4 (4 bajty). Typowy system TYPO3 ma 100 do 300 tabel, z których często 20 do 50 ma błędny zestaw znaków.

Podczas konwersji powstają polecenia ALTER TABLE dla każdej dotkniętej kolumny. Brzmi to trywialnie, ale ma pułapki: indeksy na kolumnach varchar z utf8mb4 mogą przekroczyć maksymalną długość indeksu MySQL (767 bajtów przy InnoDB ze starszymi formatami wierszy REDUNDANT lub COMPACT, czyli formatem plików Antelope). Dlatego te limity trzeba sprawdzić z wyprzedzeniem i dostosować definicje indeksów.

Dodatkowo konfiguracja TYPO3 musi deklarować zestaw znaków utf8mb4, do v11 w LocalConfiguration.php, od v12 w config/system/settings.php: ['DB']['Connections']['Default']['charset'] = 'utf8mb4' i ['DB']['Connections']['Default']['defaultTableOptions']['collation'] = 'utf8mb4_unicode_ci'. Starsze konfiguracje używają jeszcze klucza ['tableoptions']['collate'], który TYPO3 v13.4 oznacza jako przestarzały. Bez tej konfiguracji TYPO3 nadal używa utf8 dla nowych tabel.

Częste problemy to ograniczenia długości indeksu, błędy backupu i niespójne kolumny

Problem pierwszy: ograniczenie długości indeksu MySQL. Przy InnoDB ze starym formatem Compact (standard do MySQL 5.6) maksymalna długość indeksu to 767 bajtów. varchar(255) z utf8mb4 potrzebuje 1.020 bajtów miejsca indeksu. Konwersja zawodzi z “Specified key was too long”. Rozwiązanie: przełączyć ROW_FORMAT na DYNAMIC (standard od MySQL 5.7) lub zmniejszyć długość varchar w dotkniętych kolumnach.

Problem drugi: backup przed konwersją. ALTER TABLE na dużych tabelach (100.000+ wierszy) blokuje tabelę i może prowadzić do przestojów w bazach produkcyjnych. Rozwiązanie: wykonywać konwersję poza godzinami pracy i wcześniej utworzyć pełny backup. Dla dużych tabel zalecany jest pt-online-schema-change od Percona dla bezblokowej konwersji.

Problem trzeci: niespójne kolumny po częściowej konwersji. Gdy skonwertowano tylko części bazy danych, JOIN-y między kolumnami utf8 i utf8mb4 mogą prowadzić do problemów wydajności, ponieważ MySQL wykonuje niejawną konwersję zestawu znaków. Gosign po każdej konwersji sprawdza wszystkie tabele pod kątem spójności.

Od TYPO3 v9.5 rozszerzenie jest zbędne, jeśli baza danych jest poprawnie skonfigurowana

Od TYPO3 v9.5 instalator ustawia utf8mb4 jako zestaw znaków w nowych instalacjach na MySQL. Przy nowej instalacji v9.5 lub wyższej baza danych jest więc automatycznie poprawnie konfigurowana, a k3n_dvemoji nie jest potrzebne. Przestawienie pozostaje konieczne dla instalacji migrowanych z v7, v8 lub v9 na v12 lub v13, których baza danych nigdy nie była konwertowana. Gosign rozwiązuje to automatycznie w ramach każdej migracji TYPO3: wspierany przez AI skan bazy danych, pełna konwersja i kontrola spójności jako część standardowego procesu upgrade. Skan analizuje wszystkie tabele i kolumny w mniej niż 5 minut, generuje niezbędne polecenia ALTER TABLE i wykonuje je dopiero po pełnej kopii zapasowej, bo ALTER TABLE w MySQL i MariaDB nie da się wycofać transakcją; w razie błędu poprzedni stan przywraca się z kopii. Rezultatem jest baza danych, która konsekwentnie obsługuje utf8mb4 bez konieczności działania rozszerzenia w trybie pracy.