typo3db_legacy dla TYPO3

Dlaczego typo3db_legacy jest dla każdego rozszerzenia tylko pomostem

TYPO3 w wersji 8 całkowicie przestawił abstrakcję bazy danych na Doctrine DBAL. Stare API przez $GLOBALS['TYPO3_DB'] zostało w v8 oznaczone jako deprecated i od v9 jest usunięte z Core. Mimo to w praktyce tysiące instalacji TYPO3 działają z rozszerzeniami nadal opartymi na legacy API. typo3db_legacy utrzymuje te rozszerzenia przy życiu, odtwarzając stare API jako warstwę kompatybilności.

Problem: rozszerzenie nie jest rozwiązaniem trwałym, lecz mostem. Każda kolejna wersja TYPO3 zwiększa ryzyko, że sama warstwa kompatybilności ulegnie awarii. Kto dziś jeszcze korzysta z typo3db_legacy, powinien zaplanować migrację, choć wersja 1.3.0 obsługuje jeszcze TYPO3 do v14.

Typowe scenariusze zastosowań

Własne rozszerzenia z bezpośrednimi dostępami do bazy danych. Wiele agencji pisało między 2012 a 2018 rozszerzenia bezpośrednio wywołujące $GLOBALS['TYPO3_DB']->exec_SELECTquery(). W typowej instalacji średniej firmy znajduje się od 3 do 8 takich rozszerzeń. Bez typo3db_legacy po aktualizacji do v9+ natychmiast wypadłyby z Fatal Errors.

Rozszerzenia firm trzecich bez aktywnego maintainera. Rozszerzenia takie jak starsze wersje dodatków tt_address, katalogi branżowe czy specjalistyczne narzędzia importowe były często utrzymywane przez solo-deweloperów. Jeśli maintainer nie jest już aktywny, typo3db_legacy pozostaje jedyną opcją zachowania funkcjonalności przy aktualizacji.

Stopniowa migracja dużych instalacji. Firmy z ponad 50 rozszerzeniami nie mogą migrować wszystkiego jednocześnie. typo3db_legacy pozwala na stopniowe podejście: najpierw aktualizacja Core, potem rozszerzenie po rozszerzeniu na Doctrine DBAL.

Architektura techniczna

typo3db_legacy rejestruje się jako rozszerzenie TYPO3 i udostępnia klasę DatabaseConnection implementującą te same metody co stara klasa z TYPO3 Core: exec_SELECTquery(), exec_INSERTquery(), exec_UPDATEquery(), exec_DELETEquery() i warianty Prepared Statement.

Wewnętrznie warstwa buduje zapytania SQL jako tekst i wysyła je przez własne połączenie mysqli; Doctrine DBAL tylko otwiera to połączenie. To działa niezawodnie dla standardowych zapytań. Problematyczne staje się przy bazach danych innych niż MySQL i MariaDB, bo warstwa obsługuje tylko mysqli, przy Prepared Statements, które przy każdym użyciu zgłaszają deprecation, i przy transakcjach, bo stare API korzysta z drugiego połączenia. Ponadto, gdy tylko wykona się stare zapytanie, warstwa otwiera drugie połączenie z bazą danych.

Rozszerzenie zostało zaprojektowane jako tymczasowy środek. Kod celowo nie zawiera optymalizacji, które uczyniłyby je trwalszym. Brak cachowania zapytań na warstwie kompatybilności, brak integracji connection-pooling i brak wsparcia dla zaawansowanych funkcji Doctrine DBAL.

Częste problemy i rozwiązania

Rozszerzenie nie działa mimo typo3db_legacy po aktualizacji. Przyczyną jest zazwyczaj to, że rozszerzenie nie tylko używa $GLOBALS['TYPO3_DB'], ale też innych usuniętych API. Rozwiązanie wymaga kompletnej analizy kodu rozszerzenia, nie tylko wywołań bazy danych. Skan TYPO3 Extension Scannerem dostarcza priorytetyzowaną listę wszystkich miejsc.

Zapytania zwracają inne wyniki niż przed aktualizacją. Sama warstwa wysyła zapytania bez zmian przez mysqli, ale błędy typów w starym kodzie pozostają. WHERE uid = '5' (String zamiast Integer) może w skrajnych przypadkach prowadzić do niespodziewanego zachowania. Rozwiązanie: sprawdzenie wszystkich zapytań pod kątem prawidłowych typów PHP i jawne ustawienie rzutowań.

Spadek wydajności po instalacji. Instalacje z ponad 100 000 rekordami i częstymi zapytaniami odczuwają drugie połączenie z bazą danych, które otwiera warstwa. Tu pomaga tylko kompletna migracja na Doctrine DBAL z QueryBuilder, która czyni warstwę zbędną.

Migracja i kompatybilność wersji

Kod typo3db_legacy był częścią TYPO3 Core do wersji 8.7 LTS. Od TYPO3 v9 istnieje jako oddzielne rozszerzenie. Friends of TYPO3 nadal je utrzymują: wersja 1.2.0 obsługuje TYPO3 v10 do v12, a wersja 1.3.0 v12 do v14. Również pod TYPO3 v13 warstwa działa dalej.

Zalecana ścieżka migracji: każde miejsce exec_SELECTquery() jest przepisywane na Doctrine DBAL QueryBuilder. Typowe rozszerzenie z 10 do 20 wywołaniami zapytań daje się zmigrować w 4 do 8 godzin. Gosign korzysta przy tym z automatycznej analizy kodu identyfikującej wszystkie wywołania legacy API i proponującej kod migracyjny. Przy złożonych rozszerzeniach z dynamicznie budowanymi zapytaniami nakład rośnie do 2 do 3 dni per rozszerzenie.

Najczęstsze przepisania w szczegółach: exec_SELECTquery() zmienia się w $queryBuilder->select()->from()->where()->executeQuery(). exec_INSERTquery() zmienia się w $connection->insert(). Wzorzec jest konsystentny, ale każde zapytanie musi być indywidualnie sprawdzone, ponieważ stary kod często łączy stringi, które QueryBuilder oczekuje jako oddzielne parametry.