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, które adresuje ten problem, rozszerzając konfigurację bazy danych o obsługę UTF-8mb4. Od TYPO3 v10 Core jest jednak sam przygotowany na utf8mb4, dzięki czemu rozszerzenie jest potrzebne tylko przy starszych lub źle skonfigurowanych instalacjach.

Dla administratorów TYPO3 i agencji opiekujących się starszymi instalacjami k3n_dvemoji to narzędzie diagnostyczne i fix jednocześnie. Rozszerzenie identyfikuje tabele z błędnym zestawem znaków i konwertuje je, 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. k3n_dvemoji konwertuje dotknięte tabele i kolumny 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. k3n_dvemoji pomaga w późniejszej naprawie.

Trzeci scenariusz: międzynarodowe strony z językami azjatyckimi. Chińskie, japońskie i koreańskie znaki potrzebują częściowo 4 bajtów. Bez utf8mb4 pojedyncze znaki są wyświetlane okaleczone, co przy stronach z treściami CJK prowadzi do nieczytelnego tekstu. 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

k3n_dvemoji pracuje na dwóch poziomach: analizy i konwersji. W trybie analizy rozszerzenie skanuje wszystkie tabele TYPO3 i sprawdza 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.

W trybie konwersji rozszerzenie generuje polecenia ALTER TABLE dla każdej dotkniętej kolumny i wykonuje je. 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 z antique format). Rozszerzenie sprawdza te limity i dostosowuje definicje indeksów.

Dodatkowo konfiguracja TYPO3 w LocalConfiguration.php musi deklarować zestaw znaków utf8mb4: ['DB']['Connections']['Default']['charset'] = 'utf8mb4' i ['DB']['Connections']['Default']['tableoptions']['collate'] = 'utf8mb4_unicode_ci'. 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 v10 rozszerzenie jest zbędne, jeśli baza danych jest poprawnie skonfigurowana

TYPO3 v10 i wszystkie kolejne wersje oczekują utf8mb4 jako domyślnego zestawu znaków. Przy nowej instalacji v10 lub wyższej baza danych jest automatycznie poprawnie konfigurowana, a k3n_dvemoji nie jest potrzebne. Rozszerzenie pozostaje istotne 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 w transakcji, dzięki czemu w razie błędu poprzedni stan może zostać przywrócony. Rezultatem jest baza danych, która konsekwentnie obsługuje utf8mb4 bez konieczności działania rozszerzenia w trybie pracy.