Update auf TYPO3 9.5: Schritt für Schritt

Wir erklären ausführlich die einzelnen Upgradeschritte, welche Probleme auftreten können und vor allem auch wie ihr diese löst.

TYPO3 9.5, die aktuelle LTS, ist nun schon eine Weile stabil, die Kinderkrankheiten (soweit es welche gab) sind beseitigt und die meisten wichtigen Extensions sind verfügbar für diese Version. Es gibt eigentlich keinen Grund mehr, ein Update noch länger hinauszuzögern. Außerdem kommt im April 2020 ja schon die neue LTS v10 raus. Mit diesem Beitrag möchte ich Euch die Angst vor einem Update/Upgrade und der Umstellung ein wenig nehmen. Es ist eigentlich überhaupt kein Problem auf TYPO3 9.5 upzugraden. Die Upgrade Wizards nehmen euch eine Menge Arbeit ab und funktionieren zuverlässig. Also, los geht's – Schritt für Schritt!

Erst einmal die TYPO3-Extensions prüfen

Den größten Aufwand bei TYPO3-Updates verursachen die installierten Extensions. Als Erstes müsst Ihr also checken, welche TYPO3-Extensions noch gebraucht werden. Dazu verwenden wir die Extension Additional Reports. Damit sieht man, welche Plugins und Inhaltstypen tatsächlich auf welcher Seite verwendet werden.

TYPO3-Extensions: Additional Reports – gut für TYPO3-UpdatesTYPO3-Extension: Additional Reports

Anschließend müsst Ihr schauen, ob die Extensions unter der neuesten TYPO3-Version laufen werden und updaten oder ggf. Alternativen suchen. Oft findet man auf GitHub aktuellere Extension-Versionen als im TYPO3-Extension-Repository – dies war z.B. bei Grid-Elements oder DirectMail lange Zeit der Fall. Die Extension-Updates kann Euch leider niemand abnehmen, es sei den ihr bezahlt Leute dafür, dass sie das tun ;-). Macht Euch auf jeden Fall eine Liste der Exensions und haltet auch gleich mit fest, ob des ggf. Breaking Changes

TYPO3-Update mit oder ohne Composer-Umstellung?

Für alle die von TYPO3 6.2 kommen, gibt es noch eine weitere Entscheidung zu treffen: Soll die Installation auf Composer umgestellt werden oder nicht? Hier kann ich ganz klar sagen: »Ja! Macht das, es lohnt sich.« Auch wenn es erst einmal mehr Arbeit ist, wird der Composer euch doch in Zukunft sicher einiges an Ärger und Zeit sparen. Auf die Umstellung von TYPO3 auf Composer wird von mir hier näher eingegangen. In diesem Beitrag will ich mehr auf das Update eingehen.

Lokal entwickeln mit DDEV

Das Update sollte natürlich auf einer Kopie der aktuellen Seite durchgeführt werden. Niemals auf dem Live-System updaten! Bei solchen größeren Updates gibt es einfach zu viele Änderungen, vor allem in der Datenbank, die nicht so einfach wieder rückgängig zu machen sind. Wir nutzen bei uns dafür, eine lokale Entwicklungsumgebung mit der das Arbeiten deutlich angenehmer ist. Falls ihr die lokale Entwicklung ebenfalls bevorzugt oder das einfach mal machen wollt, kann ich euch DDEV empfehlen. Damit habt ihr Ruck-Zuck eine lokale Kiste bei euch laufen. Einzige Voraussetzung dafür sind Docker und Docker-Compose. Oder lasst Euch das doch einfach von Matthias erklären ... www.youtube.com/embed/HZVMPoI9SIk Falls ihr das nicht machen wollt, können die Schritte natürlich auch remote auf einem Webserver durchgeführt werden. Der Einsatz von Composer (falls ihr das machen wollt) ist remote auf dem Server – je nach Hosting-Anbieter – ebenfalls möglich.

Vertrauen ist gut. Vergleichen ist besser.

Nachdem Ihr eine Kopie der Originalseite laufen habt, erstellen wir erst einmal einen Snapshot der alten Seiten mit quibblr.it. Dieses Tool von unserem undkonsorten Eike macht uns Vorher-Nachher-Webseiten-Screenshots der gesamten Installation bzw. den Seiten, die in einer entsprechend aufbereiteten XML Sitemap angegeben sind. Ist das Update fertig lassen wir den Quibblr noch einmal über die neuen Seiten laufen und er zeigt uns alle Unterschiede zwischen vorher und nachher an. So lassen sich Probleme schnell finden. Dies hat uns v.a. bei riesigen TYPO3-Installationen mit 50.000 Seiten, wie z.B. für die Bauhaus-Uni Weimar, extrem geholfen.

TYPO3-Core-Update: Schritt für Schritt

So, nun die Schritte im einzelnen. Ich gehe mal davon aus, dass ihr mittlerweile eine Liste aller in Eurer Installation verwendeten Extensions habt und auch wisst, für welche es neuere Versionen gibt. Außerdem starte ich hier von einem TYPO3 in Version 6.2. Für die größeren Updates ist es empfehlenswert, schrittweise jede TYPO3-Major-Version (6.2 > 7.6 > 8.7 > 9.5 ) zumindest im Backend/Install-Tool mitzunehmen und bestimmte Zwischenschritte auszuführen. Die nachfolgend benannten Schritte sind dann bei jedem dieser Versionssprünge einmal abzuarbeiten. Welche dies genau sind, hängt von Eurer Installation ab. Die Wichtigsten sind:

  • Alle Extensions deaktivieren, die nicht mit dem der neuen Zielversion von TYPO3 kompatibel sind
  • TYPO3-Version updaten. In diesem Beispiel auf TYPO3 7.6:
    • neue TYPO3-Sourcen mittels wget-Befehl holen: wget get.typo3.org/7.6 Datei entpacken und Symlinks neu anlegen
    • wenn ihr keine Symlinks verwendet, eben die Ordner typo3_src und typo3 ersetzen
    • oder mit Composer die neue TYPO3 Version holen: composer require typo3/cms:^7.6
    • oder gern auch über die Oberfläche Eures Hoster

Euer Freund: Der TYPO3-Upgrade Wizard

Als nächstes solltet ihr das Install Tool von TYPO3 aufrufen und den Upgrade Wizard starten.

TYPO3 Upgrade Wizard TYPO3 Upgrade Wizard

Der Upgrade Wizard legt die benötigten Felder in der Datenbank an, ändert bestehende oder schreibt Daten um. Teilweise werden Upgrade Wizard-Schritte angeboten die Ihr nicht ausführen müsst. In der Regel handelt es sich dabei um Extensions die nachinstalliert werden müssen, um bestimmte Funktionalität von älteren TYPO3-Versionen doch noch zu nutzen oder die Schritte haben nur informativen Charakter. Der Upgrade Wizard fragt nach ob ihr den Schritt wirklich ausführen wollt. Zum Beispiel der Schritt: "Install extension rtehtmlarea from TER".

Hier müsst ihr einmal den Schritt ausführen (Button "Execute") damit er in die Liste der bereits ausgeführten Schritte wandert. Auch wenn ihr den RTE gar nicht installieren wollt. Der Schritt wird nämlich nicht sofort ausgeführt sondern es erfolgt erst noch eine Abfrage, ob ihr das wirklich tun wollt. Dort könnt ihr dann entscheiden ob ihr den alten RTE HtmlArea Editor weiter nutzen wollt.

Wenn Ihr vorhabt auf die neueste TYPO3-Version zu gehen, machen diese Schritte meistens wenig Sinn. Aber letztendlich ist das von eurer Installation abhängig.

Achtung: TYPO3-Extensions mit Upgrade Wizard

Wenn für einige Eurer verwendeten Extensions unter der jeweiligen TYPO3-Version eine Migration oder ähnliches (manchmal fügen Extensions eigene Upgrade Wizard-Schritte hinzu) für die Datenbank notwendig sind, müsst Ihr diese Extensions jetzt installieren und die notwendigen Schritte durchführen. Beispiel:Powermail verfügt in der Version 4.x über einen Upgrade Wizard für die Migration der Formulare. Dieser ist in neueren Versionen (5,6 und 7 für TYPO3 8.7) nicht mehr vorhanden. Daher muss man, wenn man weiter gehen will, an dieser Stelle einmal powermail in der Version 4.x installieren um den Wizard ausführen zu können. Ähnliches gilt für tt_address Updates > 2.x. Siehe tt_address Dokumentation. Geschafft! Das Backend sollte nun laufen. Diese Schritte sind jetzt für jede Major-Version zu wiederholen. Wenn ihr so bei TYPO3 9.5 angekommen seid, könnt ihr nach und nach alle benötigten Extensions wieder installieren und einen Blick ins Frontend wagen. Das am besten immer wenn ihr eine neue Extensions installiert habt. Dann könnt ihr einfacher die Ursache der Fehler bestimmen. Denn diese Fehler oder Dinge die jetzt anders aussehen als vorher müsst ihr nun beheben.

Häufige TYPO3-Update-Probleme

Häufige Update-Probleme sind:

css_styled_content Änderungen Bis TYPO3 8.7 könnt ihr noch css_styled_content nutzen aber das TypoScript hat sich geändert bzw. ist so nicht mehr funktionstüchtig. Hier hilft unter Umständen ein Blick in den TypoScriptObjectBrowser um die Quelle des verwendeten TypoScript-Codes zu finden. Außerdem ist die TSRef bezüglich aktueller Funktionalität hilfreich Ausgelagerte Templatedateien Sind eventuell nicht mehr eingebunden, da sich auch das TypoScript in den Extensions diesbezüglich geändert hat. Einstellungen in Plugins Die Einstellungen in Plugin werden oft im Feld pi_flexform in tt_content gespeichert. Auch hier macht das die jeweilige Extension jetzt eventuell anders. Diese Plugins sind manuell anzupassen. Bei großer Anzahl von Plugins kann das auch mit einer speziellen Datanbankanweisung gemacht werden. Auch Flexformdaten können mit MySQL ausgelesen werden und verändert werden Achtung, manchmal hilft es Inhaltselemente ganz neu anzulegen, weil in dem Datenbankfeld (pi_flexform) alte Werte nicht mehr angezeigt werden aber trotzdem noch da sind und Ärger machen!

Unter TYPO3 9.5

Problem: Template ist komplett optisch zerschossen Die Extension css_styled_content gibt es nicht mehr, fluid_styled_content kümmert sich jetzt um die Ausgabe Dazu muss jetzt natürlich das TypoScript von fluid_styled_content erstmal inkludiert werden. Außerdem muss das Templating komplett überarbeitet werden. Fluid Templates werden jetzt für tt_content Rendering verwendet. Keine Sorge, dass geht relativ fix. Wer will kann sich auch noch das alte CSS aus der css_styled_content Extensions holen und manuell einbinden. Da sind dann zwar auch noch ein paar Klassen zu ersetzen aber es hilft erst einmal. Ihr müsst halt schauen ob es Sinn macht, das CSS neu zu schreiben oder das alte weiter zu nutzen. Problem: keine Bilder mehr im Frontend für Inhalte Die Tabellenspalten für die Bilder/Medieninhalte in tt_content haben sich geändert. Bilder/Medien liegen jetzt in der Spalte assets statt vorher image oder media. Hier ein kleines SQL Snippet welche die benötigten Datenbankänderungen vornimmt und die Tabellen tt_content sowie sys_file_reference umschreibt. Außerdem wird noch der CType von textpic in den neuen textmedia umgeschrieben. Ab 7.6 kam das Feld assets dazu. Je nachdem von welcher TYPO3 Version ihr kommt oder in welcher Spalte eure Bilder liegen, muss die Query eventuell mit Ausgangsfeld oder Zielfeld angepasst werden. In dem Beipiel wird davon ausgegangen, dass die Bilder bisher im Feld image lagen und jetzt nach assets umgeschrieben werden sollen.

UPDATE tt_content 
LEFT JOIN sys_file_reference ON sys_file_reference.uid_foreign=tt_content.uid 
AND sys_file_reference.tablenames='tt_content' 
AND sys_file_reference.fieldname='image' 
SET tt_content.CType='textmedia', tt_content.assets=tt_content.image, tt_content.image=0, sys_file_reference.fieldname='assets' 
WHERE tt_content.CType='textpic' OR tt_content.CType='image';

Problem:Seiten sind in den Menüs falsch verlinkt oder gar nicht mehr aufrufbar, Einzelansichten von Extensions haben keine "schöne" Url mehr Die neue "Site-Configuration" muss für die Seite eingerichtet werden (BE Modul), für Extensions muss die config.yaml Datei von Hand bearbeitet werden. RealUrl gibt es nicht mehr. TYPO3 kümmert sich um die Url Erzeugung. Sind alle Wizards aus dem InstallTool ausgeführt? Die Extension "News" bringt zum Beispiel einen eigenen Wizard mit um die Felder für die Url umzuschreiben. Die "realurl" Datenbanktabellen müssen dazu noch vorhanden sein. Folgende Links helfen euch beim Kennenlernen der neuen "Site-Configuration".

Ihr seht, einiges an Arbeit ist es schon. Man muss sich einfach gut vorbereiten und dann abarbeiten. Natürlich hat jede Installation ihre Tücken aber das wird immer so sein. Dafür habt ihr ja aber eine Kopie angelegt und wenn gar nichts mehr geht, kann man einfach noch einmal von vorn anfangen. Mit jedem Update welches man durchführt, lernt man wieder ein paar Kniffe dazu ;-). Eure Zeit ist also gut investiert. Ich hoffe der Beitrag hilft dem einen oder anderen. Falls irgendwas unklar ist, Ihr noch Fragen habt oder Fehler entdeckt, schreibt gern einen Kommentar. Ich versuche zeitnah zu antworten und Fehler zu korrigieren. Wenn ihr bei TYPO3-Slack seid, könnt ihr auch da fragen. Bitte nicht als persönliche Nachricht sondern im öffentlichen Channel. Dann haben andere auch was davon. In diesem Sinne, Frohes Updaten!


Kommentare

Keine Kommentare


Kommentar schreiben

* Diese Felder sind erforderlich