typo3db_legacy für TYPO3

Warum typo3db_legacy für jede Extension nur eine Brücke ist

TYPO3 hat mit Version 8 die Datenbankabstraktion komplett auf Doctrine DBAL umgestellt. Die alte API über $GLOBALS['TYPO3_DB'] wurde in v8 als deprecated markiert und ist seit v9 aus dem Core entfernt. Trotzdem laufen in der Praxis tausende TYPO3-Installationen mit Extensions, die noch auf der Legacy-API basieren. typo3db_legacy hält diese Extensions am Leben, indem es die alte API als Kompatibilitäts-Layer nachbildet.

Das Problem dabei: Die Extension ist kein Dauerlösung, sondern eine Brücke. Jede weitere TYPO3-Version erhöht das Risiko, dass der Kompatibilitäts-Layer selbst bricht. Wer heute noch typo3db_legacy im Einsatz hat, sollte die Migration planen, auch wenn Version 1.3.0 noch bis TYPO3 v14 reicht.

Typische Einsatzszenarien

Eigenentwickelte Extensions mit direkten Datenbankzugriffen. Viele Agenturen haben zwischen 2012 und 2018 Extensions geschrieben, die $GLOBALS['TYPO3_DB']->exec_SELECTquery() direkt aufrufen. In einer typischen Mittelstands-Installation finden sich 3 bis 8 solcher Extensions. Ohne typo3db_legacy würden sie nach einem Update auf v9+ sofort mit Fatal Errors ausfallen.

Third-Party-Extensions ohne aktiven Maintainer. Extensions wie ältere Versionen von tt_address-Addons, Branchenverzeichnisse oder spezialisierte Import-Tools wurden oft von Solo-Entwicklern gepflegt. Wenn der Maintainer nicht mehr aktiv ist, bleibt typo3db_legacy die einzige Option, um die Funktionalität beim Upgrade zu erhalten.

Stufenweise Migration großer Installationen. Unternehmen mit 50+ Extensions können nicht alles gleichzeitig migrieren. typo3db_legacy erlaubt ein schrittweises Vorgehen: Zuerst das Core-Upgrade durchführen, dann Extension für Extension auf Doctrine DBAL umstellen. Gosign plant solche Migrationen in Sprints von je 3 bis 5 Extensions und priorisiert nach Business-Kritikalität und Abhängigkeiten.

Technische Architektur

typo3db_legacy registriert sich als TYPO3-Extension und stellt die Klasse TYPO3\CMS\Typo3DbLegacy\Database\DatabaseConnection bereit. Diese Klasse implementiert dieselben Methoden wie die alte DatabaseConnection aus dem TYPO3 Core: exec_SELECTquery(), exec_INSERTquery(), exec_UPDATEquery(), exec_DELETEquery() und die zugehörigen Prepared-Statement-Varianten.

Intern baut der Layer SQL-Strings und schickt sie über eine eigene mysqli-Verbindung, Doctrine DBAL öffnet nur diese Verbindung. Das funktioniert für Standard-Queries zuverlässig. Problematisch wird es bei:

• Anderen Datenbanken als MySQL und MariaDB, weil der Layer nur mysqli spricht
• Prepared Statements, die bei jedem Aufruf eine Deprecation-Meldung auslösen
• Transaction Handling, weil die alte API eine zweite Verbindung neben der des Core nutzt
• Performance: Sobald eine alte Query läuft, öffnet der Layer eine zweite Datenbankverbindung

Die Extension braucht außer dem TYPO3 Core nur die PHP-Erweiterung mysqli. Sie muss lediglich über Composer (friendsoftypo3/typo3db-legacy) oder das Extension Repository installiert werden.

Ein wichtiger Architektur-Aspekt: typo3db_legacy wurde als temporäre Maßnahme konzipiert. Der Code enthält bewusst keine Optimierungen, die ihn langlebiger machen würden. Es gibt kein Query-Caching auf der Kompatibilitätsschicht, keine Connection-Pooling-Integration und keine Unterstützung für die erweiterten Doctrine-DBAL-Features wie Expression Builder oder Custom-Type-Mappings. Das Design-Ziel war: Die alten Queries am Laufen halten, bis sie migriert werden.

Häufige Probleme und Lösungen

Problem: Extension funktioniert trotz typo3db_legacy nicht nach dem Upgrade. Ursache ist meist, dass die Extension nicht nur $GLOBALS['TYPO3_DB'] nutzt, sondern auch andere entfernte APIs wie $GLOBALS['TSFE']->sys_page in alter Form oder deprecated Hook-Registrierungen. Die Lösung erfordert eine vollständige Code-Analyse der Extension, nicht nur der Datenbank-Aufrufe. Ein Scan mit dem TYPO3 Extension Scanner liefert eine priorisierte Liste aller Stellen. Gosign führt solche Scans als Bestandsaufnahme durch, bevor das eigentliche Upgrade beginnt - typischer Aufwand: 2 bis 4 Stunden pro Installation mit Bericht über alle betroffenen Extensions und geschätztem Migrationsaufwand.

Problem: Queries liefern andere Ergebnisse als vor dem Upgrade. Der Layer selbst schickt die Queries unverändert über mysqli, Typfehler im alten Code bleiben aber bestehen. Ein WHERE uid = '5' (String statt Integer) kann in Edge Cases zu unerwartetem Verhalten führen. Die Lösung: Alle Queries auf korrekte PHP-Typen prüfen und Casts explizit setzen.

Problem: Performance-Einbruch nach Installation. Installationen mit mehr als 100.000 Datensätzen und häufigen Queries spüren die zweite Datenbankverbindung, die der Layer zusätzlich öffnet. Hier hilft nur die vollständige Migration auf Doctrine DBAL mit QueryBuilder, die den Layer überflüssig macht.

Migration und Versions-Kompatibilität

Der Code von typo3db_legacy war bis Version 8.7 LTS Teil des TYPO3 Core. Seit TYPO3 v9 gibt es ihn als separate Extension. Die Friends of TYPO3 pflegen sie weiter: Version 1.2.0 unterstützt TYPO3 v10 bis v12, Version 1.3.0 v12 bis v14. Beide Versionen stehen im TER und auf Packagist, inoffizielle Forks braucht es dafür nicht.

Auch unter TYPO3 v13 läuft der Layer weiter. Die Datenbankschicht des Core ist zwar auf Doctrine DBAL 4.0 umgestiegen, der Layer spricht aber direkt mysqli. Wer typo3db_legacy nutzt, kommt auf Dauer trotzdem an einer vollständigen Migration nicht vorbei.

Der empfohlene Migrationsweg: Jede exec_SELECTquery()-Stelle wird auf den Doctrine DBAL QueryBuilder umgeschrieben. Eine typische Extension mit 10 bis 20 Query-Aufrufen lässt sich in 4 bis 8 Stunden migrieren. Gosign setzt dabei auf automatisierte Code-Analyse, die alle Legacy-API-Aufrufe identifiziert und Migrationscode vorschlägt. Bei komplexen Extensions mit dynamisch zusammengebauten Queries steigt der Aufwand auf 2 bis 3 Tage pro Extension.

Die häufigsten Umschreibungen im Detail: exec_SELECTquery() wird zu $queryBuilder->select()->from()->where()->executeQuery(). exec_INSERTquery() wird zu $connection->insert(). exec_UPDATEquery() wird zu $connection->update(). Das Pattern ist konsistent, aber jede Query muss individuell geprüft werden, weil der alte Code häufig Strings zusammenkettet, die der QueryBuilder als separate Parameter erwartet. Besonders tückisch: Queries mit dynamischem WHERE-Clause-Aufbau, bei denen Bedingungen über Schleifen angehängt werden. Diese erfordern eine komplette Neustrukturierung der Logik.