Upgrade Anleitung – klassische TYPO3 Installation mit Sym-Links

Komische Fehler können jederzeit auftauchen und, wenn es blöd läuft, das Backend schon direkt zu Beginn unzugänglich machen. Um dann wenigstens ein paar Infos zur Fehlerbehebung zu bekommen, ist es besser, als erstes das Debugging einzuschalten:

Wechseln Sie ins Modul "Admin Tools">"Settings" und wählen Sie "Configuration Presets". Unter "Debug Settings" können Sie die Konfiguration von "Live" auf "Debug" umstellen.

Damit die Kopie der Website während des Upgrades nicht von Robotern gescannt wird und bei Suchmaschinen in den Ergebnissen auftaucht, sollte eine entsprechende Anweisung hinterlegt werden. Sie können dazu entweder über TypoScript

page.meta.robots = noindex, nofollow
page.meta.robots.replace = 1

setzen, oder, falls schon eine Datei "robots.txt" existiert, dort folgendes eintragen:

User-agent: *
Disallow: /

Wechseln Sie ins Backend-Modul "Extensions" und wählen Sie oben links im Menü "Get Extensions" aus. Klicken Sie dann rechts auf den Button "Update now". Nun wird eine aktualisierte Liste aller im TYPO3 Extension Repository (TER) verfügbaren Extensions geladen. (Falls auf Ihrer Website der Scheduler-Task "Update extension list (extensionmanager)" aktiv ist, wird dieser Update-Vorgang im definierten Intervall automatisch ausgeführt).

Wenn Sie jetzt oben links im Menü zurück zu "Installed Extensions" wechseln, sehen Sie links neben jeder installierten Extension ein Update-Icon, sofern eine aktuellere Version existiert. Aktualisieren Sie jede Extension auf die höchstmögliche Version, die angeboten wird.

Sollte nach dem Aktualisieren einer Extension plötzlich eine Fehlermeldung auftauchen und der Zugang zur Extension Liste nicht mehr möglich sein, können Sie die störende Extension auch über die Command Line deaktivieren. Gehen Sie dazu in das Verzeichnis typo3conf, öffnen Sie die Datei "PackageStates.php" zum Bearbeiten und entfernen Sie den Abschnitt, der zu der betreffenden Extension gehört. Löschen Sie anschließend den Cache, indem Sie das Verzeichnis typo3temp/var löschen. Nun sollte das Backend, bzw. die Extension Liste wieder zugänglich sein. Die deaktivierte Extension kann auch erst einmal in diesem Zustand bleiben, möglicherweise können Sie sie nach einem Versionsschritt wieder störungsfrei aktivieren.

Sollten in der Liste Extensions sein, die mit der nächsthöheren Major-Version von TYPO3 nicht kompatibel sind, deaktivieren Sie sie. Deaktivieren Sie auch alle individuellen Extensions und Site-Packages, die nicht im TER zur Verfügung stehen, da sie höchstwahrscheinlich nach dem nächsten Major-Versions-Schritt überarbeitet werden müssten.

Nachdem Extensions aktualisiert worden sind, kann es sein, dass es neue Upgrade Wizards gibt, die nun ausgeführt werden müssen. Wechseln Sie deshalb zum Backend-Modul "Admin Tools" > "Upgrade" und klicken Sie auf "Run Upgrade Wizard". Noch offene Wizards werden nun mit einer kurzen Beschreibung aufgelistet. Führen Sie alle Wizards aus. Falls Sie eine Nachfrage bekommen, ob Sie diesen Wizard wirklich ausführen wollen, und Sie sind sich unsicher, wählen Sie vorher "no, do not execute" aus und klicken Sie danach auf "Perform updates!". Dann wird der Wizard nicht ausgeführt, aber als "erledigt" markiert.

Nachdem die Upgrade-Wizards ausgeführt worden sind: Im Backend-Modul "Admin Tools">"Maintenance" unter "Analyze Database Structure" sollten alle Tabellen und Datenbank-Felder aktuell sein und nicht mehr benötigte gelöscht werden.

Im Backend-Modul "System">"DB Check" unter "Manage Reference Index" sollte der Index aktualisiert werden.

Für das Upgrade müssen Sie sich wieder über die Command Line auf dem Server einloggen. Schauen Sie im Verzeichnis typo3cms, ob dort schon ein Verzeichnis oder eine .tar.gz-Datei mit der TYPO3 Version liegt, die Sie benötigen. Der Name sollte lauten: typo3_src-x.x.xx, bzw. typo3_src-x.x.xx.tar.gz.

Falls die Version noch nicht vorhanden ist, können Sie sie in das Verzeichnis herunterladen mit 

wget --content-disposition https://get.typo3.org/x.x.x

Danach müssen Sie die heruntergeladene Datei entpacken mit 

tar -zxvf typo3_src-x.x.xx.tar.gz

Nun wechseln Sie in Ihr Projektverzeichnis und passen den dort existierenden Sym-Link typo3_src an, bzw. löschen Sie ihn und erstellen Sie einen gleichnamigen mit dem neuen typo3_src-x.x.xx Verzeichnis als Ziel:

rm typo3_src
ln -s ../typo3_src-x.x.xx typo3_src

Löschen Sie anschließend den Cache, indem Sie das Verzeichnis typo3temp/var löschen.

Loggen Sie sich dann direkt ins Installtool ein mit der URL v12.meine-website.de/typo3/install.php und gehen Sie folgende Punkte in dieser Reihenfolge durch:

• Upgrade-Wizards ausführen.
• TYPO3 und PHP-Cache löschen (unter Backend-Modul "Maintanance" > "Flush TYPO3 and PHP Cache").
• Analyze Database Structure ausführen. Achten Sie darauf, dass Sie zwar alle neuen Tabellen und Felder hinzufügen und ändern, aber keine Tabellen oder Felder löschen! Denken Sie daran, dass Sie Extensions vorübergehend deaktiviert haben, die diese Tabellen später beim Aktivieren vielleicht wieder brauchen.
• Loggen Sie sich jetzt ins Backend ein und schauen Sie, ob es hier irgendwelche Fehlermeldungen gibt, z.B. wenn die Extension Liste aufgerufen wird.
• Aktualisieren Sie die Extensions (auch die deaktivierten) auf den höchstmöglichen Stand für diese TYPO3-Version. Behalten Sie auch immer im Hinterkopf, bis zu welcher TYPO3 Version die jeweilige Extension noch kompatibel ist. Gibt es für die TYPO3 Version, auf die Sie im nächsten Schritt upgraden wollen, keine funktionierende Version dieser Extension mehr, dann deaktivieren Sie sie.
• Prüfen Sie, ob nach dem Aktualisieren von Extensions neue Upgrade-Wizards hinzugekommen sind.
• Lassen Sie sich nicht davon beirren, wenn aufgrund von deaktivierten Extensions oder Site-Packages Plugins oder Content-Elemente nicht gefunden werden oder im Frontend eine Fehlermeldung erscheint. Darum können Sie sich kümmern, wenn die Zielversion erreicht ist.

Wiederholen Sie den Schritt "Upgrade auf eine Zwischenversion bzw. die Zielversion" so lange, bis Sie die Zielversion erreicht haben. Achten Sie auch bei jedem Schritt darauf, ob die soeben erreichte TYPO3 Version noch mit der PHP-Version Ihrer Domain funktioniert und passen Sie diese gegebenenfalls an.

Spätestens hier wird es sehr individuell, da es darauf ankommt, was die Start- und was die Zielversion von TYPO3 ist und wo sich Ihr Site Package bisher befindet bzw. ob es überhaupt eines gibt. Darum hier nur einige grundlegende Infos und Tipps zur Vorgehensweise:

• Wenn sich das Site Package bzw. die Designvorlage in einem Verzeichnis unterhalb von fileadmin befindet, sollten Sie diese spätestens ab TYPO3 Version 11 auslagern in das Verzeichnis typo3conf/ext. Wie man ein Sitepackage für TYPO3 in diesem Verzeichnis erstellt und es dann wie eine Extension in der Extension Liste installiert, erfahren Sie auf https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/
• Um ein bestehendes Site Package an die neue TYPO3 Version anzupassen, halten Sie sich ebenfalls an das oben genannte Tutorial und überprüfen Sie vor allem die Dateien
  • composer.json
  • ext_emconf.php
  • ext_localconf.php
  • ext_tables.php
  • Configuration/TCA/Overrides/sys_template.php
  • Configuration/TCA/Overrides/pages.php
  • Configuration/TCA/Overrides/tt_content.php
  • sowie weitere PHP-Dateien
• Prüfen Sie, ob eingesetzte TypoScript Conditions noch funktionieren. Ab TYPO3 9.4 basiert die Condition Syntax auf der Symfony Expression Language, weshalb an vielen Stellen die alte in die neue Syntax umgeschrieben werden muss. Probleme mit Conditions erkennen Sie an einem entsprechenden Eintrag in der Log-File (Verzeichnis typo3temp/var/log).
• Auch im Site Package verwendete ViewHelper müssen nach einem Upgrade häufig angepasst oder ersetzt werden, weil es sie so in der neuen Version nicht mehr gibt. Das erkennen Sie an einer entsprechenden Fehlermeldung im Frontend.

Wenn Sie das Site-Package (bzw. sonstige individuelle Extensions) vollständig an die neue TYPO3 Version angepasst haben, können Sie dieses wieder aktivieren, prüfen ob alles funktioniert und gegebenenfalls weitere Anpassungen vornehmen.

Extensions aus dem TER, die während des Upgrade-Prozesses deaktiviert wurden, können nun auch wieder aktiviert werden.

Nun sollte sowohl das Backend als auch das Frontend wieder einwandfrei laufen.

In der Datei LocalConfiguration.php bzw. settings.php oder im InstallTool unter "GFX" den Wert für 'processor_colorspace' wie folgt anpassen:

'processor_colorspace' => 'sRGB'

Danach im InstallTool unter "Maintanance > Remove Temporary Assets" die Verzeichnisse leeren, aus denen die zu dunklen Bilder kommen.

• PHP-Version auf >= 8.1 umstellen
• in PHP-Dateien die Konstante 'TYPO3_MODE' 

  ​if (!defined('TYPO3_MODE')) {     die('Access denied.'); }

   ändern in 'TYPO3'

  if (!defined('TYPO3')) {     die('Access denied.'); }

• PHP-Version auf >= 7.4 umstellen
• .htaccess-Datei anpassen, z.B. die Beispiel-Datei vom TYPO3 11 Core verwenden: typo3/sysext/install/Resources/Private/FolderStructureTemplateFiles/root-htaccess
• Endung der Typoscript- und TSConfig Dateien umbenennen von .txt zu .typoscript bzw. .tsconfig
• in PHP-Dateien die Variable $_EXTKEY durch den Verzeichnisnamen des Sitepackages ersetzen (außer in der Datei "ext_emconf.php")

Wenn der Upgrade-Check ergeben hat, dass Ihre Website noch css_styled_content verwendet, muss spätestens beim Schritt von TYPO3 v7 nach TYPO3 v8 css_styled_content nach fluid_styled_content migriert werden.

Verwenden Sie Subparts und/oder Marker in Ihren Templates, müssen diese in Fluid-Templates umgebaut werden. Das gleiche gilt auch, wenn Sie eine veraltete Extension wie zum Beispiel templavoila, rlmp_tmplselector oder automaketemplate für das Templating einsetzen.