Umstellung einer TYPO3 Installation auf Composer

Was ist eigentlich Composer? Kurz gesagt ist Composer ein Paketmanager für PHP der in der Regel über Befehle in der Konsole/Terminal bedient wird. Es gibt auch grafische Tools, die habe ich aber noch nie getestet. Wenn ihr es genauer wissen wollt findet ihr jede Menge Infos im Netz. Ein erster Anlaufpunkt für die Nutzung mit TYPO3 ist https://composer.typo3.org. Dort gibt es auch einen Link der die Installation beschreibt.

Viele zweifeln noch und überlegen ob sie sich damit befassen sollen und nicht einfach weiter wie bisher ihr TYPO3 aufsetzen sollen. Ich persönlich glaube, dass sich die Umstellung lohnt und jetzt, wo sowieso größere Updates fällig sind, der richtige Zeitpunkt dafür gekommen ist. Der Composer gibt euch einfach die Möglichkeit viele einzelne Schritte bei der täglichen Arbeit mit dem CMS nach und nach zu automatisieren. Selbst wenn ihr noch kein Deployment bei euch einsetzt bringt der Composer Vorteile. Die genaue Prüfung der Abhängigkeiten der einzelnen Pakete ist sicher manchmal nervig, bringt aber Sicherheit und Stabilität in eure Anwendung. Und wenn irgendwas nicht passt, verweigert der Composer eben die Installation.

Mit welcher TYPO3 Version kann ich den Composer nutzen?
Wann sollte ich umstellen?

Der Composer macht Sinn ab der TYPO3 Version 7.6. Unter 6.2 soll er zwar auch funktionieren aber das macht nach meiner Recherche keinen Spaß und ist eher nicht zu empfehlen. Macht irgendwie auch keinen Sinn, da die 6.2er Version schon ewig nicht mehr unterstützt wird. TYPO3 7.6 wird zwar auch nicht mehr unterstützt, diese Version braucht man aber unter Umständen noch um bei Updates die von 6.2 auf 8.7 / 9.5 durchgeführt werden sollen, notwendige Schritte vom UpgradeWizard durchzuführen. Eh ich's vergesse. Mittlerweile nutze ich für solche Sachen immer eine lokale Entwicklungsumgebung. Die geht Dank DDEV, Docker und Docker-Compose mittlerweile echt gut und ist fix aufgesetzt. Jetzt aber weiter im Text.

Zuerst ist eine kleine Anpassung der Ordnerstruktur notwendig. Im wesentlichen gibt es ein Projekt Root-Verzeichnis (dort liegt später die composer.json und composer.lock Datei), einen Public Ordner (meistens web oder auch public genannt) und einen Vendor Ordner. Den Vendor Ordner braucht ihr nicht erstellen. Das macht Composer später automatisch. Den Public Ordner müsste ihr jetzt erstellen. Dort kommen die Ordner "fileadmin, uploads, typo3conf (und ein leeres ext Verzeichnis)" aus eurem alten TYPO3 Verzeichnis rein. Die Ordner typo3, typo3temp und die index.php oder eben ihre Symlinks braucht ihr nicht.

Da ihr später ja auch eure Extensions mittels Composer installieren wollt, ist es notwendig, dass ihr euch eine Liste mit den verwendeten Extension erstellt. Inklusive der genutzten Version. Dabei kann man auch gleich schauen welche Extension wirklich noch benutzt wird und für welche eventuell ein Update möglich ist. Dabei ist die Extension additional_reports ein gutes Hilfmittel.

Jetzt steht ihr kurz davor euer TYPO3 mit Composer zum Leben zu erwecken. Dafür benötigt ihr nun eine composer.json Datei. Diese muss im Projekt-Rootverzeichnis plaziert werden. Der Aufbau wird auf composer.typo3.org sehr gut beschrieben. Dort gibt es auch einen Befehl mit dem ihr eine neue leere TYPO3 Installation erstellen könnt.

Die nächsten Schritte sind abhängig von der gewählten TYPO3 Version. Ich fange hier einmal mit TYPO3 7.6 an, da einige vielleicht von TYPO3 6.2 aus updaten wollen und dabei auf Composer umsteigen möchten. Der Befehl composer require typo3/cms:^7.6 installiert für euch TYPO3 in der letzten frei verfügbaren 7.6er Version. TYPO3 7.6 ist ja mittlerweile auch nur noch als ELTS verfügbar. Da diese Version nur als Zwischenschritt benötigt wird, ist es aber kein Problem, dass sie veraltet ist und eigentlich nicht mehr supported wird.

Jetzt habt ihr in eurem Verzeichnis einen zusätzlichen Ordner vendor. Dort liegen nun alle Pakete die TYPO3 7.6 zum funktionieren benötigt. Der Composer hat sich um alle Abhängigkeiten gekümmert und die benötigten Pakete geladen. Ihr könnt euch nun ins Backend einloggen. Die Domain zeigt dabei auf euren Public Ordner. Außerdem hat der Composer eine Datei composer.lock angelegt. Diese ist wichtig, da in ihr immer der aktuelle Stand aller installierten Pakete abgebildet ist. Der Befehl composer install kann anhand dieser Datei immer den aktuellen Stand installieren. Bei Arbeiten im Team ist es über diese Datei möglich jederzeit den Stand bei einem Projekt an andere Teammitglieder zu übergeben. Meistens geschieht das dann über ein Remote Repository einer Versionsverwaltung. Was ihr da nutzt bleibt euch überlassen. So langsam könnt ihr jetzt anfangen nach und nach alle benötigten Extensions mittels dem Kommando composer require typo3-ter/extkey-mit-als-trennung:versionsnummer neu zu installieren. Oft sind die Extensions auch über einen eigenen Paketnamen (vendorname/extension-key) auf packagist.org veröffentlicht. Dann könnt ihr auch diesen nehmen. Das ist sogar ausdrücklich empfohlen. Ob das bei einer Extension der Fall ist, verrät euch ein Blick ins TER, die Suche auf packagist.org oder ein Blick in die composer.json Datei der meist auf Github veröffentlichten Extension. Kleiner Tipp, seit geraumer Zeit habt ihr in dem neuen Extensions Repository von TYPO3, in der Extension Detailansicht, einen Link auf das Github Repo der selbigen. Hierbei müsst ihr jetzt natürlich aufpassen auf welche Version ihr geht bzw. wo ihr herkommt. Dabei hilft euch die Liste eurer Extensions die ihr vorher angelegt hattet. Wenn es Probleme mit Abhängigkeiten bestimmter Extensions gibt, wird der Composer euch darauf aufmerksam machen und die Installation verweigern. Wie schon angesprochen kann das sehr nervig sein und wird am Anfang einiges an Zeit kosten bis man die Meldungen richtig interpretiert. Aber auch dazu findet ihr mittlerweile jede Menge Infos und Tipps im Netz.

Solltet ihr alles geschafft haben, könnt ihr euch ins Backend einloggen und auf den "Extensions Manager" wechseln. Dort seht ihr jetzt oberhalb eine Meldung, dass eure TYPO3 Installation mit Composer läuft und Extensions nur noch über diesen hinzugefügt und entfernt werden können. Eine Installation direkt im Backend ist nun nicht mehr möglich. Was eure Installation auch gleich wieder ein Stück sicherer macht. Über den Dateimanager, einen SSH oder FTP Zugang könnt ihr natürlich immer noch Extensions in den entsprechenden Ordner hochladen oder löschen aber dann werden aber weder Abhängigkeiten geprüft noch das automatische ClassLoading aktualisiert. Was schließlich dazu führen kann, dass eure gerade hinzugefügte Extension die Seite kaputt macht.

Wie läuft das Updaten von TYPO3 mit Composer?

Hier ist jetzt nicht mehr ganz soviel notwendig. Ein Großteil ist abhängig von den verwendeten Extensions und ob sie mit der neueren TYPO3-Version kompatibel sind. Wir wollen nun die neueste Version von TYPO3 8.7 installieren. Dazu müssen wir folgenden den Befehl verwenden: 

composer require typo3/cms:^8.7 --update-with-dependencies 

Der Befehl composer update typo3/cms würde hier nicht helfen, da er nur nach einer neuen TYPO3 Version im Versionszweig von 7.6 suchen würde. Das wird durch das vorangestellte "^" bei der Versionsnummer festgelegt. Genauere Infos findet ihr hier Composer versioning. Falls ihr Probleme mit nicht kompatiblen Extensions bekommt, müsst ihr diese entweder in den require Befehl mit aufnehmen oder sie erst einmal entfernen. Das könnt ihr mit composer remove [packagename] --no-update gefolgt von composer remove [packagename] erledigen. Das require Kommando von Composer kann einfach mehrere Pakete auf einmal holen indem ihr sie mit Leerzeichen getrennt hintereinander schreibt.

Beispiel:

composer require typo3/cms:^8.7 georgringer/news:^7 --update-with-dependencies

Wenn alles durchläuft und der Composer nicht meckert, habt ihr's geschafft. Euer TYPO3 sollte jetzt mit 8.7 laufen. Ab TYPO3 9.5 kommt jetzt noch eine kleine aber wichtige Änderung ins Spiel. Der TYPO3 Core wird nicht mehr allein durch das Paket typo3/cms installiert. Der Core wurde in viele kleine Pakete aufgeteilt. Dadurch hat man die Möglichkeit TYPO3 auf seine ganz speziellen Bedürfnisse abzustimmen und muss nicht immer das große Ganze nutzen. Die Basis ist und bleibt aber das Paket typo3/cms-core. Dies kann man aber nicht allein installieren/requiren. Da man nicht unbedingt weiß welche Pakete man eigentlich genau benötigt, gibt es diese Hilfestellung: TYPO3 Composer Packages. Da kann man fix zwischen "Full", Minimal" und "Default" wählen. Dann bekommt man eine Liste die man hinterher aber noch anpassen kann. Schaut einfach selbst.

Diesen Code führt man dann einfach im Terminalfenster aus und schon hat man seine neue TYPO3 Version mit genau den Paketen die man wirklich braucht oder haben will. Die üblichen Probleme mit den Extensions bleiben natürlich. Auch hier muss man sich darum kümmern, dass bei einer Installation die Extensions kompatibel sind.

Wenn ihr TYPO3 ab 9.5 dann später updaten wollt, also kein Sprung auf eine neue MajorVersion sondern einfach nur die kleinen Updates, könnt ihr folgenden Befehl nehmen um alle notwendigen Pakete zu erwischen.

composer require typo3/cms-* --with-dependencies

Hilfe zu den Composerbefehlen findet ihr in der Dokumentation von Composer.

Und jetzt, fröhliches Composern! Ich hoffe ihr habt daran bald genau so viel Spaß wie ich. Noch ein Tipp zum Schluß. Wenn ihr mal eine Extension oder gar den Core patchen müsst, das geht mit Composer total geil ;-). Und über die composer.lock ist der Patch auch noch nach jedem Update automatisch wieder drin. Dazu braucht ihr eigentlich nur dieses Package:  cweagans/composer-patches. Vielleicht schreib ich dazu demnächst mal noch einen Beitrag.