TYPO3 na Composer – dlaczego, kiedy i jak przejść

W skrócie: TYPO3 można zainstalować klasycznie (tryb Legacy, pliki przez FTP) albo przez Composer. Dla aktualnych wersji 13 i 14 zalecaną drogą jest Composer, a wiele rozszerzeń pojawia się najpierw albo wyłącznie w Composerze. Przejście najlepiej połączyć z aktualizacją wersji. Treści, drzewo stron i użytkownicy zostają, zmienia się tylko struktura plików.

Wiele stron na TYPO3 założono lata temu klasycznie: pobrana paczka z typo3.org, wgrana przez FTP, rozszerzenia instalowane w Extension Managerze. To działa do dziś. Najpóźniej przy aktualizacji do TYPO3 13 albo 14 pojawia się jednak pytanie, czy nie przejść od razu na Composer.

Nazwy menu dotyczą TYPO3 do wersji 13. W TYPO3 14 część modułów panelu ma nowe nazwy, np. „Admin Tools” to teraz „Administration” albo „System”.

Na czym polega różnica?

Tryb Legacy: rdzeń TYPO3 leży na serwerze jako paczka plików, rozszerzenia w typo3conf/ext/. Aktualizacja to wgranie nowej paczki, zmiana dowiązań (symlinków) i aktualizacja rozszerzeń po kolei.

Tryb Composer: plik composer.json opisuje, która wersja TYPO3 i które rozszerzenia w jakich wersjach są zainstalowane. Composer wszystko pobiera i pilnuje, żeby wersje do siebie pasowały. Aktualizacja to jedno polecenie plus test, a konfigurację można trzymać w Git.

Dlaczego warto przejść

• Sprawdzanie zależności. Composer odmówi instalacji, jeśli rozszerzenie nie pasuje do wersji TYPO3, zamiast żeby coś wybuchło później na żywej stronie.
• Przejrzyste aktualizacje. Która wersja działa, widać w pliku, a nie tylko w panelu.
• Lepsza dostępność rozszerzeń. Wiele rozszerzeń pojawia się najpierw na Packagist, w katalogu paczek dla Composera.
• Bezpieczniejsza struktura. W trybie Composer serwer WWW wskazuje tylko na folder public/. Konfiguracja, logi i kod są poza nim i nie da się ich otworzyć z internetu.

Co jest potrzebne

• Dostęp SSH do serwera albo możliwość zbudowania projektu lokalnie i wgrania wyniku. Wielu hostingodawców oferuje dziś SSH także w mniejszych pakietach.
• Możliwość ustawienia katalogu głównego domeny (Document Root) na folder public/. U większości hostingodawców robi się to w panelu.
• Lista wszystkich zainstalowanych rozszerzeń z wersjami i źródłem: z TER, z Packagist albo własne.

Jak przebiega przejście

1. Kopia zapasowa plików i bazy danych.
2. Spis rozszerzeń. Dla każdego trzeba ustalić nazwę paczki Composera. Własne rozszerzenia dostają własny composer.json i trafiają do lokalnego folderu, zwykle packages/.
3. Nowy projekt z composer.json, rdzeniem TYPO3 i wszystkimi rozszerzeniami w pasujących wersjach.
4. Przeniesienie treści. Folder fileadmin/ trafia do public/fileadmin/. Konfiguracje stron są w config/sites/, a ustawienia systemowe od TYPO3 12 w config/system/settings.php.
5. Podłączenie bazy danych, a potem w „Admin Tools → Maintenance” sprawdzenie struktury bazy i wyczyszczenie cache.
6. Test w środowisku testowym: strona, panel, formularze, wyszukiwarka, obrazy i przekierowania.
7. Uruchomienie przez przełączenie Document Root na nowy folder public/. Stara wersja zostaje jako zabezpieczenie.

Typowe pułapki

• Rozszerzenia bez paczki Composera. Części starych rozszerzeń z TER nie ma na Packagist. Trzeba je wtedy dołączyć lokalnie albo zastąpić.
• Sztywne ścieżki w kodzie. Własne rozszerzenia i TypoScript czasem odwołują się wprost do typo3conf/ext/. Trzeba to zmienić na ścieżki EXT:.
• Pliki poza fileadmin. Obrazy albo PDF-y leżące gdzie indziej w katalogu strony łatwo pominąć przy przenosinach.
• Brak SSH u hostingodawcy. Wtedy projekt buduje się lokalnie i wgrywa gotowy. To działa, ale jest bardziej uciążliwe. Czasem lepszym wyjściem jest zmiana hostingu.

Razem z aktualizacją

Kto i tak musi przejść z TYPO3 10, 11 albo 12 na aktualną wersję, powinien zrobić przejście na Composer przy tej samej okazji. Wszystkie rozszerzenia i tak trzeba wtedy sprawdzić i zaktualizować. O przebiegu i kosztach aktualizacji piszę w artykule Aktualizacja TYPO3 10/11 do 14, a o sytuacji wersji 12 w TYPO3 12 – koniec wsparcia.

Profesjonalna pomoc

Przenoszę strony TYPO3 na Composer, zwykle w ramach aktualizacji do TYPO3 14 LTS, i przekazuję udokumentowaną, wersjonowaną instalację. Więcej w usłudze aktualizacja TYPO3 i na stronie TYPO3 – strony, aktualizacje i opieka.