k3n_dvemoji für TYPO3: Emoji-Support & UTF-8mb4-Migration

Emojis als Fragezeichen sind kein Darstellungsproblem, sondern ein Datenbank-Konfigurationsfehler

Wenn in einem TYPO3-Backend ein Redakteur ein Emoji eingibt und im Frontend stattdessen ein Fragezeichen oder ein leeres Kästchen erscheint, liegt das Problem nicht im Browser und nicht in TYPO3. Es liegt in der MySQL- oder MariaDB-Datenbank, die mit dem Zeichensatz utf8 statt utf8mb4 konfiguriert ist. Der Unterschied: utf8 speichert maximal 3 Bytes pro Zeichen, Emojis brauchen 4 Bytes. k3n_dvemoji ist eine TYPO3-Extension zu diesem Problem, die weder im TER noch auf Packagist oder GitHub veröffentlicht ist; wie sie es im Einzelnen löst, lässt sich deshalb nicht prüfen. Seit TYPO3 v9.5 richtet der Installer bei neuen Installationen allerdings selbst utf8mb4 ein, sodass eine Umstellung nur noch bei älteren oder falsch konfigurierten Installationen nötig ist.

Für TYPO3-Administratoren und Agenturen, die ältere Installationen betreuen, braucht es deshalb Diagnose und Fix zugleich: Tabellen mit falschem Zeichensatz finden und konvertieren, was manuell ein fehleranfälliger Prozess ist.

Typische Einsatzszenarien betreffen ältere Installationen, Migrationen und internationale Inhalte

Das häufigste Szenario ist eine TYPO3-v8- oder v9-Installation, die seit Jahren läuft und deren Datenbank noch auf utf8 (nicht utf8mb4) konfiguriert ist. Schätzungsweise 30% aller TYPO3-Installationen, die vor 2018 eingerichtet wurden, haben dieses Problem, weil die Installationsroutine damals utf8 als Standard setzte. Solange Redakteure nur lateinische Zeichen verwenden, fällt das nicht auf. Sobald ein Social-Media-Post mit Emoji auf der Website eingebettet wird oder ein Redakteur ein Emoji in eine Überschrift setzt, bricht die Darstellung. Die Lösung ist, die betroffenen Tabellen und Spalten auf utf8mb4 zu konvertieren.

Zweites Szenario: Datenbank-Migrationen zwischen Servern. Beim Umzug einer TYPO3-Datenbank von einem alten Server auf einen neuen kann der Zeichensatz durch einen fehlerhaften mysqldump-Befehl verloren gehen. Ein Dump mit —default-character-set=utf8 statt utf8mb4 schneidet alle 4-Byte-Zeichen ab. Dann müssen Zeichensatz und Import nachträglich richtiggestellt werden.

Drittes Szenario: Internationale Websites mit asiatischen Sprachen. Die gebräuchlichen chinesischen, japanischen und koreanischen Schriftzeichen belegen in UTF-8 drei Bytes, seltene und historische Ideogramme ab CJK Extension B aber vier. Ohne utf8mb4 lassen sich diese Zeichen nicht speichern und erscheinen verstümmelt. Auch mathematische Symbole, Musiknoten und diverse Sonderzeichen aus dem Unicode-Bereich oberhalb von U+FFFF sind betroffen, was für Hochschul-Websites und wissenschaftliche Portale relevant ist.

Technische Architektur analysiert und konvertiert Datenbank-Tabellen auf Spaltenebene

Eine Umstellung arbeitet auf zwei Ebenen: Analyse und Konvertierung. Bei der Analyse werden alle TYPO3-Tabellen gescannt und der Zeichensatz jeder Spalte geprüft. Das Ergebnis ist ein Report, der zeigt, welche Tabellen und Spalten noch auf utf8 (3 Byte) statt utf8mb4 (4 Byte) stehen. Ein typisches TYPO3-System hat 100 bis 300 Tabellen, von denen oft 20 bis 50 einen falschen Zeichensatz aufweisen.

Bei der Konvertierung entstehen ALTER TABLE Statements für jede betroffene Spalte. Das klingt trivial, hat aber Fallstricke: Indizes auf varchar-Spalten mit utf8mb4 können die maximale Index-Länge von MySQL überschreiten (767 Bytes bei InnoDB mit den älteren Zeilenformaten REDUNDANT oder COMPACT, also dem Dateiformat Antelope). Deshalb müssen diese Limits vorab geprüft und die Index-Definitionen angepasst werden.

Zusätzlich muss die TYPO3-Konfiguration den Zeichensatz utf8mb4 deklarieren, bis v11 in der LocalConfiguration.php, ab v12 in der config/system/settings.php: ['DB']['Connections']['Default']['charset'] = 'utf8mb4' und ['DB']['Connections']['Default']['defaultTableOptions']['collation'] = 'utf8mb4_unicode_ci'. Ältere Konfigurationen verwenden noch den Schlüssel ['tableoptions']['collate'], den TYPO3 v13.4 abkündigt. Ohne diese Konfiguration nutzt TYPO3 weiterhin utf8 für neue Tabellen.

Häufige Probleme sind Index-Längenbeschränkungen, Backup-Fehler und inkonsistente Spalten

Problem eins: MySQL-Index-Längenbeschränkung. Bei InnoDB mit dem alten Compact-Format (Standard bis MySQL 5.6) ist die maximale Index-Länge 767 Bytes. Ein varchar(255) mit utf8mb4 braucht 1.020 Bytes Index-Platz. Die Konvertierung scheitert mit “Specified key was too long”. Die Lösung: ROW_FORMAT auf DYNAMIC umstellen (Standard ab MySQL 5.7) oder die varchar-Länge in den betroffenen Spalten reduzieren.

Problem zwei: Backup vor der Konvertierung. Ein ALTER TABLE auf großen Tabellen (100.000+ Zeilen) sperrt die Tabelle und kann bei Produktionsdatenbanken zu Ausfällen führen. Die Lösung: Konvertierung außerhalb der Geschäftszeiten durchführen und vorher ein vollständiges Backup erstellen. Bei großen Tabellen empfiehlt sich pt-online-schema-change von Percona für eine lockfreie Konvertierung.

Problem drei: Inkonsistente Spalten nach teilweiser Konvertierung. Wenn nur Teile der Datenbank konvertiert wurden, können JOINs zwischen utf8- und utf8mb4-Spalten zu Performance-Problemen führen, weil MySQL eine implizite Zeichensatz-Konvertierung durchführt. Gosign prüft nach jeder Konvertierung alle Tabellen auf Konsistenz.

Ab TYPO3 v9.5 ist die Extension überflüssig, wenn die Datenbank korrekt konfiguriert ist

Seit TYPO3 v9.5 richtet der Installer bei Neuinstallationen auf MySQL utf8mb4 als Zeichensatz ein. Bei einer Neuinstallation mit v9.5 oder höher ist die Datenbank damit automatisch korrekt konfiguriert, und k3n_dvemoji ist nicht nötig. Nötig bleibt eine Umstellung für Installationen, die von v7, v8 oder v9 auf v12 oder v13 migriert werden und deren Datenbank noch nie konvertiert wurde. Gosign löst das im Rahmen jeder TYPO3-Migration automatisch mit: KI-gestützter Datenbank-Scan, vollständige Konvertierung und Konsistenz-Check als Teil des Standard-Upgrade-Prozesses. Der Scan analysiert alle Tabellen und Spalten in unter 5 Minuten, generiert die nötigen ALTER TABLE Statements und führt sie erst nach einem vollständigen Backup aus, denn ALTER TABLE lässt sich in MySQL und MariaDB nicht per Transaktion zurückrollen; bei einem Fehler wird der vorherige Zustand aus dem Backup wiederhergestellt. Das Ergebnis ist eine Datenbank, die utf8mb4 durchgängig unterstützt, ohne dass eine Extension im Betrieb nötig ist.