Upgrade von Typo3 4.x auf Typo3 6.2

28. März 2015

Warum sollte man jetzt auf die Version 6.2 upgraden?

Wenn man nicht ständig die Neuerungen der jeweils aktuellen Version nutzen möchte, bietet es sich an, in größeren Zeitabständen die sogenannten LTS-Versionen von Typo3 einzusetzen. LTS steht dabei für Long Term Support und bedeutet, dass für diese Version für einen längeren Zeitraum Bug fixes und Sicherheits-Updates zur Verfügung gestellt werden. Für die vorige LTS-Version Typo3 4.5 läuft dieser Support nun am 31. März 2015 aus. Darum ist es wichtig, jetzt alle Typo3-Projekte möglichst kurzfristig auf die nächste LTS-Version, die Version 6.2, upzudaten. Für Typo3 6.2 wird es laut Release Notes bis mindestens März 2017 Support geben, wie man auf der Website » http://typo3.org auch in einer schönen Grafik sehen.

Typo3 Release Agenda

Die TYPO3 Association und das TYPO3 Entwicklerteam bieten allen, die das Upgrade bisher noch nicht durchgeführt haben, die Möglichkeit, für ein weiteres Jahr Sicherheitsupdates für die Version 4.5 zu erhalten. Dieser Support ist jedoch kostenpflichtig.

Typo3-Websites, die nicht mehr gewartete Versionen von Typo3 verwenden, laufen Gefahr, Opfer von Cyber-Attacken zu werden. Sollten durch solche Attacken wiederum Schäden bei anderen Internet-Nutzern entstehen, sind wegen der Missachtung elementarer Sorgfaltspflichten sogar Schadens­ersatz­ansprüche gegenüber den Website­betreibern denkbar. 

Wie sieht nun generell die Situation in der Typo3-Gemeinde aus? Beim Blick auf die Website » http://t3census.info tut sich Erschreckendes auf: Mit dem Stand vom 21. Dezember 2014 waren erst 5,8% der untersuchten 359.281 Typo3-Websites auf einem Stand, der nach dem 31. März 2015 noch supportet wird.

Wir haben darum in diesem Artikel unsere Erfahrungen bei den von uns durchgeführten Upgrades aufgeschrieben und hoffen, anderen damit bei der Umstellung zu helfen.

Vorbereitungen

Bevor mit dem eigentlichen Update begonnen werden kann, sollten die folgenden Vorbereitungen getroffen werden:

Sicherung erstellen

Wenn man keinen separaten Entwicklungsbereich hat, in dem die Durchführung des Updates vorab getestet werden kann, ist es wichtig, dass man von seiner Website eine komplette Sicherung besitzt. Diese Sicherung besteht aus zwei Teilen: Der Datenbank und dem Typo3-Dateibaum. Die Datenbank kann mit folgendem Kommando aus der Shell heraus gesichert werden:

mysqldump --opt -h "$host" -u "$user" -p"$pwd" "$db" | gzip >$backupdir/databases/${backuptag}_db.sql.gz

Der Typo3-Dateibaum wird als komprimiertes tar-Archiv ebenfalls in Sicherheit gebracht:

tar -czf $backupdir/files/${backuptag}_typo3.tar.gz $typo3dir

In den obigen Kommandozeilen müssen die mit dem $-Zeichen beginnenden Shell-Variablen durch die jeweils korrekten Werte ersetzt werden. Wichtig ist, dass man kein einziges Bit an seiner Website ändert, ehe diese Sicherungen vorhanden und am besten noch auf den heimischen Rechner transportiert und dort auf Korrektheit hin überprüft worden sind.

Es ist sicher auch zu empfehlen, während der Arbeit an dem Upgrade mehrere Backups anzulegen, damit man in dem Falle einer Zerstörung der Typo3-Installation nicht wieder ganz von vorne anfangen muss.

Überprüfung der verwendeten PHP- und MySQL-Versionen

Bezüglich der verwendeten PHP- und MySQL-Versionen finden sich in der Typo3-Dokumentation zur Version 6.2 LTS die folgenden Hinweise:

  • PHP › 5.3.7 up to 5.5 (PHP 5.4 or later recommended)
  • MySQL 5.1 up to 5.6 or compatible (no "strict mode")

Diese Versionsüberprüfungen und -veränderungen können normalerweise am bequemsten über die Verwaltungskonsole des Providers vorgenommen werden.

PHP-Fehlermeldungen beim Seitenaufruf anzeigen lassen

Der zweite ganz wichtige Punkt ist, dass man die PHP-Optionen so ändert, dass im Falle eines fatalen Fehlers in einem PHP-Skript eine Fehlermeldung im Browser angezeigt wird, die einem hilft, das Problem zu beseitigen. Über das Typo3-Install-Tool wird dazu der Punkt All configuration aufgerufen und dort der Wert der Variablen displayErrors am besten auf 2 gesetzt. In Verbindung mit dem Eintrag der eigenen IP-Adresse in der Einstellung devIPmask bewirkt dies, dass Fehlermeldungen auf dem jeweiligen Entwicklungsrechner ausgegeben werden. Wenn man keine feste IP-Adresse hat, sollte man displayErrors auf -1 setzen und das Verhalten der Website über die php.ini steuern. Im Zweifelsfall fragt man seinen Provider, was zu tun ist. Fehlermeldungen können zum Beispiel auch in der Log-Datei des Webservers nachgeschaut werden, was aber umständlicher als eine Ausgabe im Browser ist.

Entpacken der Typo3-Source-Dateien

Nun sollten die Typo3-Source-Dateien auf den Webserver kopiert werden, falls der Provider dies nicht schon getan hat. Die jeweils aktuelle Version findet sich am besten hier » http://typo3.org/download. Im Regelfall kopiert man sich die Datei auf seinen Rechner und lädt sie dann mit Hilfe seines ftp-Zugangs in seinen Webspace. Es ist üblich, dass die Source-Dateien eine Verzeichnisebene unterhalb des Wurzelverzeichnisses der Website liegen. Dorthin sollte man die tar-Datei mit den Typo3-Sourcen auch kopieren und das Archiv dann zum Beispiel mit Hilfe des Kommandos

tar xvf typo3_src-6.2.9.tar.gz

entpacken.

Den Referenz-Index auf Konsistenz hin überprüfen

Damit die Skripte im Rahmen des eigentlichen Upgrades ohne Fehler durchlaufen werden, muss der sogenannte Referenz-Index von Typo3 überprüft und gegebenenfalls korrigiert werden. Dies geschieht in der Typo3-Umgebung in der Rubrik DB-Check unter dem Menüpunkt Check and update global reference index. In einer kleineren Typo3-Website klickt man einfach auf Check reference index und bei gefundenen Fehlern auf Update reference index. Dieser Vorgang muss eventuell mehrere Mal wiederholt werden, bis keine Inkonsistenzen mehr gefunden werden. Bricht die Ausführung dieser Operation wegen zu langer Laufzeit ab, muss man über die Shell die auf derselben Seite stehenden Kommandos eingeben. Zu beachten ist in diesem Zusammenhang noch, dass bei manchen Providern der PHP-Interpreter nicht mit dem Kommando php sondern mit dem Kommando php5 aufgerufen wird.

Spalte Extension-Typ im Extension-Manger einblenden

Alle weiteren Schritte bei der Vorbereitung des Upgrades beziehen sich nun auf die Überprüfung der Kompatibilität der verwendeten Extensions. Im Rahmen eines Typo3-Upgrades werden alle System-Extensions automatisch aktualisiert. Um die muss man sich also nicht kümmern. Anders sieht es bei den Nicht-System-Extensions aus. Um diese überhaupt erst einmal zu ermitteln, blendet man im Extension-Manager den Typ der installierten Extensions ein. Dazu klickt man in der Kopfzeile der Extension-Übersicht auf einen der kleinen Pfeile rechts neben den Spaltentiteln und aktiviert dort die Option Spalten / Typ. Danach wird in einer neuen Spalte der Typ der Extensions angezeigt. Im weiteren Verlauf untersucht man alle Extensions vom Typ Local. Achtung: Diese Darstellungsmöglichkeit gibt es leider nicht in allen Typo3-Versionen und insbesondere auch nicht mehr in der hier betrachteten Version 6.2 LTS.

Lokale Extensions löschen, updaten oder vormerken

Bei der Behandlung der Extensions müssen nun die folgenden Fälle unterschieden werden:

  • Vermutet man, dass eine bestimmte Extension nicht verwendet wird, so deinstalliert man sie. Danach sollte man für den Fall, dass man sich irrt, die Funktion seiner Website überprüfen. Bewahrheitet sich die Vermutung, so wird die nicht verwendete Extension komplett entfernt. Was nicht vorhanden ist, kann beim Update auch nicht stören.
  • Wird eine Extension verwendet, informiert man sich im TER (Typo3 Extension Repository) über den Kompatibilitäts-Zustand der entsprechenden Extension. Dort findet man in meistens Fällen in der Rubrik Dependencies Informationen zu Abhängigkeiten von den unterschiedlichen Typo3-Versionen. Gibt es eine gemeinsame Version der Extension sowohl für die momentan aktive Typo3-Version als auch für die Version 6.2, so kann diese über den Extension-Manager entsprechend aktualisiert werden. Da wir uns nicht darauf verlassen, dass der Extension-Manager auf alle Abhängigkeiten in unserem Sinne achtet, laden wir die Extension-Dateien als t3x-Dateien herunter und installieren diese händisch.
  • Gibt es für die momentan aktive Typo3-Version und die Version 6.2 keine gemeinsame Extension, so verändert man an der aktuellen Typo3-Installation zunächst nichts, sondern lädt die für die Version 6.2 benötigte Extension-Datei nur herunter und installiert diese später nach der Durchführung des eigentlichen Upgrades.
  • Problematisch sind die Extensions, bei denen man im Typo3-Repository keine Kompatibilitäts-Informationen findet (z.B. rlmp_tmplselector) oder für die definitiv keine zur Version 6.2 kompatiblen Versionen zur Verfügung stehen (z.B. multicolumn). In ersterem Fall kann man das Upgrade trotzdem versuchen und hoffen, dass die Extension auch mit Typo3 6.2 läuft bzw. man die Extension eventuell selbst anpassen kann. Im zweiten Fall muss man vor dem Upgrade einen Ersatz für die Extension schaffen - multicolumn kann man zum Beispiel durch gridelements ersetzen.

Abschließender Datenbank-Check

Ist man bis zu diesem Punkt vorgestoßen, so empfiehlt sich ein Datenbank-Check über die COMPARE-DATABASE-Funktion im Install-Tool von Typo3. Stimmt die Datenbank komplett mit dem Soll-Zustand überein, so ist man nun für den eigentlichen Upgrade-Schritt gerüstet.

Verwenden der Extension smoothmigration

Wir haben erst nach der Durchführung unserer Upgrades von der Extension smoothmigration gelesen. Darum können wir zu deren Verwendung keine weiteren Informationen geben. Grundsätzlich soll die Extension den Übergang zur Version 6.2 LTS erleicherten. Weitere Informationen finden sich unter der URL  » http://typo3.org/extensions/repository/view/smoothmigration.

Anpassungen von eigenen piBase-Extensions

Wir mussten in unseren eigenen piBase-Extensions die folgende Anpassungen vornehmen, damit diese unter der Version 6.2 weiterhin funktionieren:

require_once

Anweisungen der Art

require_once(PATH_tslib.'class.tslib_pibase.php');

werden ersetzt durch

if (!class_exists('tslib_pibase')) require_once(PATH_tslib . 'class.tslib_pibase.php');

Zugriff auf mySQL-Datenbanken

Die früher verwendeten Anweisungen 

$this->mydb = t3lib_div::makeInstance('t3lib_db');
$this->mydb->link = 
  $this->mydb->sql_pconnect($host,$dbname, $password);
$this->mydb->sql_select_db($dbname);

können nicht mehr verwendet werden.

Die Verbindung zu einer mySQL-Datenbank wird statt dessen nun folgendermaßen hergestellt:

$this->mydb = new \TYPO3\CMS\Core\Database\DatabaseConnection();
$this->mydb->connectDB($host, $user, $password, $dbname);

Debug-Meldungen

Früher benutzten wir die Funktion

t3lib_div::debug($info, $titel)

Diese müssen jetzt folgendermaßen umgeschrieben werden:

t3lib_utility_Debug::debug($info, $titel)

Durchführung des eigentlichen Upgrades

Wenn die Vorbereitungen sorgfältig gemacht wurden, ist jetzt eigentlich gar nicht mehr so viel zu tun. Wir sind in den folgenden Schritten vorgegangen:

Umhängen des Source-Trees

Die Aktivierung einer neuen Typo3-Version ist vom Provider abhängig. Die hier beschriebenen Schritte können deshalb nur als Vorlage dienen:

Man geht mit der Shell in das Wurzel-Verzeichnis der Typo3-Website - das ist das Verzeichnis, in dem sich zum Beispiel die Datei .htaccess und die Unterverzeichnisse typo3 und typo3conf befinden. Hier gibt man jetzt das folgende Kommando ein:

rm -f typo3_src; ln -s ../typo3_src-6.2.9 typo3_src; cp -f typo3_src/index.php .

Die obige Befehlszeile besteht aus drei aneinandergehängten Kommandos:
rm -f typo3_src  löscht den symbolischen Link typo3_src aus dem Wurzelverzeichnis der Website,
ln -s ../typo3_src-6.2.9 typo3_src  legt ihn neu an und
cp -f typo3_src/index.php .  kopiert die Datei index.php aus dem Source-Tree in das Stammverzeichnis der Website.

Nach Ausführung dieser Kommandos ist der Source-Tree der Version 6.2.9 aktiv.

Wenn inzwischen eine neuere Version von Typo3 6.2 aktuell sein sollte, wählt man entsprechend die neuere Release-Nummer.

Das Kopieren der index.php in das Stamm-Verzeichnis ist notwendig, weil bei unserem Provider die index.php kein symbolischer Link sein darf.

Ausführen des Upgrade-Wizards

Wenn man das Typo3-Backend der Website nun im Browser aufruft, sollte man direkt zum Upgrade-Wizard weiter geleitet werden.

Nicht erschrecken, wenn man statt dessen eine Fehlermeldung sieht! In der Regel kann man das Problem selbst beheben oder findet bei » GitHub einen Patch für die betroffene Extension. Kommt man gar nicht weiter, geht man einfach wieder zurück zur alten Version, indem man die Kommandos zum Umhängen des Source Trees wieder für die zuvor verwendete Version aufruft.

Falls man aber bis zum Upgrade-Wizard kommt, ist man schon einen großen Schritt weiter. Man führt nun der Reihe nach alle vorgegebenen Upgrade-Schritte durch. Dabei sollte man sicherheitshalber einen Schritt erst dann ausführen, wenn der vorige Schritt erfolgreich durchgelaufen ist. Ausnahmen sind hier die beiden Schritte zu FAL (File Abstraction Layer) und RTE (Rich Text Editor), die auch zu einem späteren Zeitpunkt noch durchführt werden können, weil die Lauffähigkeit des Systems nicht davon abhängt.

Behebung von sonstigen Problemen

Nun sollte man, immer noch im Install-Tool, bei den beiden Punkten System environment und Folder structure vorbeischauen und vorgeschlagene Berichtigungen vornehmen. Ist dieses geschehen, geht man noch zu den Important actions und leert dort den Cache. Außerdem kann man dort überprüfen, ob alle aktiven Extensions geladen werden können, ohne das System zu beschädigen.

Installation von Extensions, die in der neuen Version nicht lauffähig sind

Nun ist der Zeitpunkt gekommen, die Extensions zu updaten, für die es für Typo3 6.2 eine neue Version gibt. Eine solche Extension ist zum Beispiel static_info_tables.

Upgrade von Typo3-Websites mit templavoila

Zu unserer großen Erleichterung gibt es inzwischen auch für Typo3 6.2 eine Version der Extension templavoila.

Bei uns gab es beim Upgrade einer großen Website in fünf Sprachen zunächst ein Problem mit der Mehrsprachigkeit: Die Übersetzungen wurden nicht mehr angezeigt. Das wurde aber vom zuständigen Autor mit der Version 1.9.7. umgehend behoben.

Probleme beim Upgrade oder danach

Fatal error: ... require_once()...

Manchmal passiert es, dass man nach dem Upgrade im Frontend oder im Backend eine Fehlermeldung der Art Fatal error: ... require_once()... sieht.

Auch hier gilt: Fehlermeldung genau lesen - vielleicht bezieht sie sich auf eine selbstgeschriebene Extension und man kann das Problem selbst beheben.

Ansonsten hilft oft eine gründliche Bereinigung des Verzeichnisses /typo3temp. Vorher sicherheitshalber ein Backup machen!

Das Bereinigen macht man am besten im Install-Tool im Bereich Clean up. Hier gibt es oben den Button "Empty selected folders". Unter "Number of files at a time" wählt man z.B. 500 und ruft "Empty selected folders" auf, bis keine Dateien mehr gelöscht werden. Dasselbe dann auch noch für die Unterverzeichnisse - dazu wählt man im Dropdown "From sub-directory" die Verzeichnisse aus, die (viele) Dateien enthalten.

Problem mit Links und FAL: Reference index was probably out of date

Beim Upgrade auf Typo3 6.2. werden die Links auf Dateien auf FAL (File Abstraction Layer) umgestellt. Hierbei tritt möglicherweise ein Fehler auf - zum Beispiel für Inhaltselemente, die verborgen ("hidden") oder gelöscht ("deleted") sind, oder auch im Zusammenhang mit Templavoila. Dies führt dann im Update Wizard im Schritt "Migrate all file links of RTE-enabled fields to FAL" zu einer Warnung: 

"Updating the reference index: This script bases itself on the references contained in the general reference index (sys_refindex). It is strongly advised to update it before running this wizard."

Im weiteren Verlauf des Upgrade Wizards erscheint dann die Fehlermeldung "Update failed!" - gefolgt von einer langen Liste mit Einträgen der Art:

"fileadmin/XY not fount in referenced element (uid: XY of table tt_content... ). Reference index was probably out of date."

In der "Typo3-Schmiede" findet man dazu unter » Bug #61154 einen Eintrag mit folgendem Tipp:

Prüfe zunächst, ob die Fehlermeldungen im Upgrade-Wizard sich mit dem Ergebnis des folgenden SQL-Statements decken:

SELECT * FROM sys_refindex WHERE softref_key = 'typolink_tag' AND ref_table = '_FILE';

Wenn die Daten - erwartungsgemäß - übereinstimmen, können die Einträge mit folgendem SQL-Statement korrigiert werden:

UPDATE sys_refindex SET softref_key = 'typolink' WHERE softref_key = 'typolink_tag' AND ref_table = '_FILE';

Mit diesem Workaround haben wir dieses Problem beim Upgrade für alle unsere Websites lösen können.

Abschließender Datenbank-Vergleich

Läuft die Website nun fehlerfrei unter 6.2 und ist dies durch ausreichende Tests bestätigt, so empfiehlt sich das Aufräumen der Datenbank, in dem man im Install-Tools unter Important actions mit Hilfe des Database analyzers die Typo3-Datenbank auf den Soll-Zustand hin überprüft und alle im Rahmen des Upgrades ausgesonderten Elemente endgültig entfernt. Ist auch dieser Schritt vollzogen, ist man mit dem Upgrade auf Typo3 6.2. endlich fertig.

Bei unserem Provider Jochen Weiland werden die wichtigen Sicherheitsupdates automatisch im Rahmen täglich ablaufender Skripte eingespielt. Darum müssen wir uns (im besten Fall :-)) um Typo3-Updates bis zum Frühjahr 2017 nicht mehr kümmern.

Kommentare

  • Sebastian
    am 04.05.2016
    Das hat geholfen. Super. Danke

Neuen Kommentar schreiben