typo3db_legacy für TYPO3

Warum typo3db_legacy seit TYPO3 v12 ein Sicherheitsrisiko für jede Extension ist

TYPO3 hat mit Version 8 die Datenbankabstraktion komplett auf Doctrine DBAL umgestellt. Die alte API über $GLOBALS['TYPO3_DB'] wurde ab v9 als deprecated markiert und ist seit v12 vollständig 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, steht vor einer klaren Entscheidung - migrieren oder das Upgrade auf v13 riskieren.

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 v10+ 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 grosser 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 leitet der Layer alle Aufrufe an Doctrine DBAL weiter. Das funktioniert für Standard-Queries zuverlässig. Problematisch wird es bei:

• Direkten MySQL-Funktionen in Queries (z.B. GROUP_CONCAT, datenbank-spezifische Syntax)
• Prepared Statements mit benannten Parametern im alten Format
• Transaction Handling über die alte API, das nicht 1:1 auf Doctrine mappt
• Performance: Jeder Query durchläuft eine zusätzliche Abstraktionsschicht mit 5-15% Overhead

Die Extension hat keine eigenen Abhängigkeiten ausser dem TYPO3 Core selbst. Sie muss lediglich über Composer (typo3/cms-typo3db-legacy) oder das Extension Repository installiert werden.

Ein wichtiger Architektur-Aspekt: typo3db_legacy wurde als temporäre Massnahme 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. Doctrine DBAL behandelt Typen strenger als die alte mysqli-basierte API. 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 den Overhead der doppelten Abstraktion messbar. Hier hilft nur die vollständige Migration auf Doctrine DBAL mit QueryBuilder, die den Layer überflüssig macht.

Migration und Versions-Kompatibilität

typo3db_legacy war offizieller Bestandteil des TYPO3 Core bis Version 9.5 LTS. Für TYPO3 v10 und v11 existierte die Extension als separates Composer-Paket. Für TYPO3 v12 LTS gibt es keinen offiziell unterstützten Release mehr. Inoffizielle Forks auf GitHub versuchen die Kompatibilität herzustellen, sind aber weder vom Core-Team noch von der Extension-Owners-Gruppe getestet.

Für TYPO3 v13 ist kein Kompatibilitäts-Layer geplant oder realistisch. Die Datenbankschicht hat sich mit dem Upgrade auf Doctrine DBAL 4.0 zu stark verändert. Wer typo3db_legacy nutzt und auf v13 upgraden will, kommt 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.