Upgrade von Drupal 9 auf 10
Die Migration von Drupal 9 auf Drupal 10 steht an, weil Drupal 9 nach November 2023 nicht mehr aktualisiert wird.
Drupal 10 bringt einige Neuerungen.
Ein Upgrade ist also nicht nur alternativlos, sondern ein weiterer Fortschritt in Sachen Sicherheit, Performance, Barrierefreiheit und Bedienbarkeit.
Das Upgrade ist einfacher, als bei früheren Versionssprüngen. Aber man muss schon auch wissen, was man tut.
In diesem Blog-Artikel informieren wir über
- die Neuigkeiten
- welche Werkzeuge es gibt, die das Upgrade vereinfachen
- den Standard-Prozess des Upgrades
- Tipps, falls es zu Fehlermeldungen kommt.
Inhaltsverzeichnis
Was ist neu in Drupal 10?
u.a.
- Das Claro-Admin-Theme ersetzt das Seven Theme
- Neues Standardtheme Olivero ersetzt Bartik.
- CKEditor 5 bringt noch mehr Bedienfreundlichkeit beim Einpflegen von Texten und Medien..
- Es gibt die Theme Starter Kit Tools für die Erstellung von eigenen Themes.
- Symfony 6 ist obligatorisch und das erfordert PHP 8.1.
- Es gibt einen Projekt-Browser, um im Backend direkt neue Module zu finden
- Die Core-Updates laufen automatisiert (noch experimentell).
- Bessere Layout Builder Funktionen erlauben Laien die Pflege von Inhalten in Blöcken und Spalten ohne Programmierkenntnissen.
- Es gibt bessere Bibliotheken für die Front-End-Entwicklung.
Checkliste vor Upgrade
- Ist die Seite komplett unter Composer Kontrolle?
- Wurde die Core Version der Installation auf die neueste (zuletzt veröffentlichte) Version von Drupal 9 (mindestens 9.4) aktualisiert?
- Bietet der Hoster die notwendigen System Voraussetzungen für Drupal 10?
https://www.drupal.org/docs/system-requirements/php-requirements - Ist PHP im Frontend, wie auch auf der Konsole, in Version mindestens 8.1 verfügbar?
- Wurde mit composer why-not php 8.1 gecheckt, ob einzelne Pakete ein Update brauchen, um unter 8.1 zu laufen?
- Verwendet das Projekt drupal/core-recommended oder drupal/core?
Prüfe mit
composer show drupal/core-recommended
Falls drupal/core-recommended installiert ist, werden die Pakete aufgezählt, andernfalls kommt
"Package drupal/core-recommended not found"
Wir unterstellen im weiteren Verlauf die Verwendung von drupal/core-recommended
Aktualisiere die Drupal Installation auf die letzte Version 9, mindestens 9.4.*
Temporär Rechte verändern
chmod 777 web/sites/default
chmod 666 web/sites/default/*settings.php
chmod 666 web/sites/default/*services.yml
Update zur aktuellen Drupal 9 Core Version
composer require drupal/core-recommended:9.5.4 drupal/core-composer-scaffold:9.5. 4 drupal/core-project-message:9.5.4 --update-with-all-dependencies
Datenbank-Update
drush updatedb
Rechte wieder zurück stellen
chmod 755 web/sites/default
chmod 644 web/sites/default/*settings.php
chmod 644 web/sites/default/*services.yml
Update der PHP Version
Prüfe mit
composer require php:"^8.1" --no-update
ob alle installierten Pakete kompatibel sind zu PHP 8.1
Diese Version kann auch in der composer.json im Bereich require eingetragen werden.
"require": {
"php": ">=8.1"
}
Und danach mit update installiert werden:
composer update php
Auf der Konsole stelle ich ebenfalls die Version für PHP auf 8.1.
Das funktioniert bei meinem Hoster All-inkl so:
ln -sfv /usr/bin/php81 /usr/bin/php
Vorarbeiten mit dem Modul Upgrade Status
Installiere die aktuelle Version des Moduls mit Composer und Drush, wie hier beschrieben:
https://www.drupal.org/project/upgrade_status
Das kann Upgrade Status:
- Prüft, ob Du eine Version von Drupal verwendest, die ein Upgrade unterstützt.
- Prüft, ob das System die Systemanforderungen der nächsten Hauptversion erfüllt.
- Interagiert mit Update Status, um über die Versionen der installierten Module zu informieren.
- Führt phpstan-Prüfungen und eine ganze Reihe anderer Prüfungen durch, um eventuell noch vorhandene Kompatibilitätsprobleme mit der nächsten Drupal-Hauptversion zu finden
- Arbeitet mit drush zusammen
Nach der Installation ist der Upgrade Status Report hier aufzurufen:
www.deinedomain.de/admin/reports/upgrade-status
Das sehen wir auf dem Bild:
Die roten Meldungen bezüglich Core-Version verschwinden nach oben beschriebenem Update auf aktuelle Drupal 9-Version.
Die PHP-Version stellen wir beim Hoster für diese Domain auf mindestens 8.1.
Die veralteten Berechtigungen für nicht mehr vorhandene Paragraphen oder deinstallierte Module müssen entfernt werden.
Das funktioniert aber erst, wenn die entsprechenden Module und Themes deinstalliert und auch mit composer entfernt wurden.
Deshalb überspringen wir diesen Punkt zuerst und kümmern uns erst um den nächsten Punkt im Upgrade Status Report.
Deprecated Modules
Im Upgrade Status Report werden auch veraltete Module angezeigt, die in Drupal 10 nicht mehr unterstützt werden.
Das sind z.B. CKEditor 4, Color, Quick Edit, RDF, Bartik und Seven.
Bei Dir können das weitere Module oder Themes sein.
Hier gibt es weitere Infos dazu:
https://www.drupal.org/node/3223395
Je nach Art des Modules wird es beim Upgrade auf D10 automatisch entfernt, oder es muss vorab entfernt werden.
Beim CKEditor ist folgendes Vorgehen die Lösung:
- Wir aktivieren im Backend den CKEditor 5, der in neueren D9 Versionen bereits zur Verfügung steht.
- Wir gehen in die Konfiguration der Text-Formate und stellen dort jedes Textformat, das bisher mit CKEditor bearbeitet wird, auf CKEditor 5 um und speichern diese Konfiguration.
- Danach deaktivieren wir ckeditor im Backend.
Für Module, die auf CKEditor 4 basieren und für die es kein CKEditor 5-Äquivalent gibt, benötigenwir individuelle Lösungen.
Dazu hier eine Übersicht:
https://www.drupal.org/docs/core-modules-and-themes/core-modules/ckedit…
Im Backend werden seit dem Update auf die letzte Drupal 9-Version weitere Module als deprecated gekennzeichnet:
Wir deaktivieren diese Module und entfernen sie mit Composer:
composer remove drupal/quickedit
composer remove drupal/color
Falls z.B. Quickedit weiter benutzt werden soll, so gibt es dafür ein Modul, das man installieren kann. Es wurde nur aus dem Core entfernt.
Deprecated Themes
In unserem Fall betrifft das neben Seven und Bartik auch das Verwaltungstheme Adminimal, für das wir unter Drupal 9 ein angepasstes Subtheme verwendet haben.
Das Theme Claro, das bereits installiert ist, aber noch nicht verwendet wird, setzen wir im Backend unter Design als Verwaltungstheme, anstelle von Adminimal Subtheme:
Danach können wir sowohl das Admininmal Subtheme, als auch das Adminimal Theme deinstallieren.
Ebenso deinstallieren wir Seven und Bartik - erst im Backend und dann mit Composer:
composer remove seven
composer remove bartik
composer remove adminimal
Danach überzeugen wir uns in der composer.json, ob der Eintrag für
"drupal/admin_toolbar": "~3.1.0",
im Bereich require verschwunden ist.
Und prüfen, ob die Themes aus dem core/themes bzw. web/themes/contrib Ordnern verschwunden sind.
Andernfalls löschen wir die Einträge bzw. Ordner händisch und entfernen auch aus web/themes/custom das Subtheme für adminimal.
Deinstallierte Module entfernen
Im Upgrade Status Report werden auch Module angezeigt, die irgendwann einmal aktiviert waren und sich noch im web/modules/contrib Ordner befinden, aber nicht mehr benötigt werden.
Diese Module machen künftig nur Arbeit und sind evt. nicht mit Drupal 10 kompatibel.
Deshalb entfernen wir sie restlos, auch mit composer remove <modulname>.
Danach führen wir ein Datenbank Update durch:
drush updb
Cache leeren ist nie verkehrt:
drush cache-rebuild
Nun können wir in den Upgrade Status Reports diese Meldungen ankreuzen:
und danach ganz unten
wählen.
Danach ist dieser Bereich verschwunden.
Custom Module und Themes aktualisieren
Die nächste Meldung betrifft die Individual-Module und Subthemes, die sich normalerweise in den Ordnern web/modules/custom bzw. web/themes/custom befinden.
Je nachdem, welche Funktionen in den Modulen oder in der Datei subtheme/subtheme.theme verwendet werden, sind vielleicht weitergehende Aktionen notwendig, um die Kompatibilität mit Drupal 10 zu bekommen. In der Regel müssen hier nur die Zeilen
core_version_requirement: ^8 || ^9
auf
core_version_requirement: ^9 || ^10
aktualisiert werden.
Falls es auch noch eine Zeile
core: 8.x
gibt, so muss die unbedingt entfernt werden.
Bei umfangreichen eigenen Modulen oder Theme-Funktionen rentiert ein Blick auf diese Seite, um veralteten Code zu finden:
https://drupalize.me/tutorial/what-deprecated-code
Wenn wir in diesem Abschnitt Haken setzen und unten auf Elemente Scannen klicken, dann ändert sich häufig in der Ansicht nichts.
Wir ignorieren das.
Module auf neuen Stand bringen
Im Bereich "Aktualisieren" werden im Upgrade Status Report alle Module angezeigt, für die es eine neuere Version gibt.
So beherzigen wir den Hinweise, der hier steht "Es ist ein Update verfügbar. Auch wenn dieses nicht vollständig mit der nächsten Hauptversion des Drupal.Kernsystems kompatibel ist, kann es kompatibler sein als die von Ihnen verwendete Version. Aktualisieren Sie das Modul deshalb dennoch."
composer update "drupal/*" --with-all-dependencies
drush updatedb
drush cache-rebuild
Wenn wir danach die Standard-Übersicht für Aktualisierung der Module aufrufen, werden wir feststellen, dass einige Module noch als veraltet gekennzeichnet werden.
Dies betrifft vor allem Module, für die noch keine stabile Version vorliegt, sondern alpha/beta/rc-Versionen, die mit Drupal 10 kompatibel sind.
Hier geben wir die gewünschte Version ausdrücklich an.
composer require drupal/inline_entity_form:2.0.0-rc9
Module, die nicht mit Drupal 10 kompatibel sind
Wir finden diese Module in einem bestimmten Bereich des Upgrade Status Reports.
Zum jetzigen Zeitpunkt sind zu meiner großen Freude fast alle Module, die ich gerne verwende, in einer Version verfügbar, die mit Drupal 10 kompatibel sind.
Es hat schon seine Gründe, warum ich seit mindestens Drupal 8 die Anzahl der Module möglichst beschränke und nur solche einsetze, die sich allgemeiner Beliebtheit und Verbreitung erfreuen.
Bei diesen Modulen ist die Wahrscheinlichkeit groß, dass sie gepflegt werden oder eines Tages in den Core wandern.
Zum Zeitpunkt meiner ersten Upgrades lagen viele Module noch nicht für Drupal 10 vor.
Wie geht man nun mit solchen Modulen um?
Hier ein Diagramm für die Entscheidungsfindung:
Es versteht sich von selbst, dass die Prüfung der Module auf Kompatibilität in einem sehr frühen Konzept-Stadium ansteht und mit dem Kunden abgestimmt werden muss, wenn solche Module installiert sind, die nicht kompatibel sind. Diese stehen auch einem Fixpreis für das Upgrade im Wege.
Upgrade auf Drupal 10
Wir unterstellen, dass unser Upgrade Status Report nun lauter grüne Bereiche hat und schreiten zum eigentlichen Upgrade.
Bei mir hat sich eine ganz bestimmte Reihenfolge als sinnig erwiesen, um Fehlermeldungen zu vermeiden.
Das variiert je nach Installation und beinhaltet immer etwas Ersuch und Irrtum.
Ich kann nur dringend empfehlen, jeden vorherigen Schritt zu dokumentieren und an bestimmten Stellen - z.B. JETZT - ein vollständiges Backup von Dateien und Datenbank zu erstellen, um bei Problemen nicht alle vorherigen Schritte noch einmal durchführen zu müssen.
1. Schritt: Aktualisierung von Drush auf Version 11:
composer require drush/drush:^11
2. Schritt: Anpassung der Drupal Version in der composer.json ohne eigentliches Update:
composer require drupal/core-recommended:^10 drupal/core-composer-scaffold:^10 drupal/core-project-message:^10 --update-with-dependencies --no-update
Die Verwendung des --no-update-Flags aktualisiert die composer.json-Einträge, ohne Dateien herunterzuladen.
Dies ermöglicht es uns, Aktualisierungen von Projekten unter Umgehung eines "Henne-und-Ei"-Problems vorzubereiten.
Alternativ könnten wir die Versionseinschränkungen in der composer.json-Datei auch manuell bearbeiten.
3. Schritt: Aktualisierung von Drush auf Version 12:
composer require drush/drush:^12 --no-update
Auch dieser Schritt erfolgt mit dem no-update-Flag
4. Schritt: Aktualisierung der Composer-Version:
Vielleicht ist dieser Schritt bei Dir nicht notwendig.
Bei mir kam es im Zuge des Updates zu einer Fehlermeldung bezüglich zu niedriger Composer 2.* Version.
Deshalb machen wir das besser sofort.
composer self-update
Den Schritt können wir bei Reue (oder Fehlermeldungen) jederzeit mit
composer self-update --rollback
rückgängig machen.
5. Schritt: Gebe höhere Rechte auf bestimmte Dateien
chmod 777 web/sites/default
find web/sites/default -name "*settings.php" -exec chmod 777 {} \;
find web/sites/default -name "*services.yml" -exec chmod 777 {} \;
6. Schritt: Eigentliches Update
Wir verwenden den Flag --with-all-dependencies, um alle Abhängigkeiten zu berücksichtigen.
composer update --with-all-dependencies
drush updatedb
drush cache-rebuild
Ohne Cache-rebuild kommt es oft zu einer hässlichen Fehlermeldung beim Aufruf im Frontend.
Deshalb mache ich das zur Nervenschonung routinemäßig.
7. Schritt: Setze die Rechte wieder zurück
chmod 755 web/sites/default
find web/sites/default -name "*settings.php" -exec chmod 644 {} \;
find web/sites/default -name "*services.yml" -exec chmod 644 {} \;
8. Schritt: Blick ins Backend auf die Reports
Wenn wir nun den Statusbericht bzw. die Seite mit den verfügbaren Aktualisierungen ansehen, sollten wir die Drupal Core Version 10.* sehen, sowie die Module alle in Grün.
9. Schritt: Testen, Testen, Testen!!!
Troubleshooting
Beschrieben wurde ein relativ einfaches Upgrade.
In der Regel läuft es nicht so smart, sondern es kommt zu Meldungen auf der Konsole oder wie oben im Upgrade Status Report, denen man nach gehen muss.
1. Upgrade Status Report: Probleme mit Berechtigungen in der Konfiguration.
Diese veralteten Berechtigungen für nicht mehr vorhandene Paragraphen oder deinstallierte Module müssen entfernt werden.
Das funktioniert aber erst, wenn die entsprechenden Module und Themes deinstalliert und auch mit composer entfernt wurden.
Wenn wir diesen Ordner aufrufen, bzw. den Unterordner sync., so ist dieser unter Umständen leer oder enthält veraltete Konfigurationen.
Den aktuellen Stand speichern wir per Drush dort hin:
drush config:export
Uns interessieren diese drei Dateien:
Sie enthalten die Berechtigungen der Benutzerrolle: "Gast", "angemeldeter Benutzer" und "Redakteur".
In allen drei Dateien müssen die Zeilen mit Hinweis auf Rechte bezüglich "blockinhalte" gelöscht werden. Da gab es anfangs einen gleichnamigen Paragraphen, den ich dann aber gelöscht habe.
Wir suchen also in allen drei Dateien die entsprechenden Rechte, die im Upgrade Status Protokoll angemahnt werden.
Nun sollen die so geänderten Konfigurations-Dateien wieder in die aktuelle Konfiguration importiert werden.
drush config:import
Evt. kommt es beim Durchführen dieses Befehls zu Fehlermeldungen auf der Console.
Bei mir betraf das eine Konfigurationsdatei bezüglich Seven-theme.
Solche Dateien veralteter bzw. nicht mehr vorhandener Themes darf man einfach aus dem Konfigurationsordner entfernen.
Dann Drush Import noch mal testen.
Ich hatte auch schon den Fall, wo noch die gleichen Fehlermeldungen kamen.
Da half es, den Drush Cache leeren.
drush cc
Danach sollte der Abschnitt im Upgrade Status Report verschwunden sein.
2. Fehlermeldungen beim Update-Befehl
Manchmal führt composer update in eine Vielfalt von Fehlermeldungen, die nicht aufgelöst werden können.
In dem Fall machen wir erst mal einen Trockenversuch. Das geht mit:
composer why-not drupal/core-recommended 10.0
oder
composer update "drupal/core:10.0" --dry-run
Beide Befehle sollten die gleichen Ergebnisse der Analyse liefern, aber die Darstellung ist etwas unterschiedlich.
Z.B. kommt es zu Fehlermeldungen dieser Art:
drupal/recommended-project - does not require symfony/console (but v4.4.49 is installed)
Eine Suche im Netz führt zu dieser hilfreichen Seite:
https://www.drupal.org/project/drupal/issues/3335486 und wir führen diesen Befehl durch:
composer show --no-dev --direct --name-only | xargs
Auf die damit erzeugte Liste an Paketen machen wir ein Update, wie vorgeschlagen.
composer require <Liste-der_Pakete-mit-Leerzeichen-getrennt> --update-with-all-dependencies
Und nun sollten die Updates alle erfolgen.
3. Module müssen gepatched werden
Meistens finden wir in den Issues eines Module, das nicht kompatibel ist zu Drupal 10 einen Link zu einem Artikel »Drupal 10 compatibility«.
Vorausgesetzt, die Hinweise stimmen uns optimistisch, dass der Patch funktioniert, dann updaten wir das Modul mit Composer zuerst auf das genannte Release.
z.B. https://www.drupal.org/project/tablefield/releases/8.x-2.x-dev
Dann schieben wir den Patch aus Kommentar #6 aus
https://www.drupal.org/project/tablefield/issues/3289933#comment-146633…
in das Verzeichnis: /web/modules/contrib/tablefield
Danach wechseln wir auf der Konsole in diesen Ordner und führen den Befehl
git apply < namedespatches.patch
aus.
Kommt es dabei zu einer Fehlermeldung, probieren wir es mit:
patch -p1 < namedespatches.patch
Danach kontrollieren wir die info.yml Datei .
Hier steh manchmalt noch die Zeile core: 8.x, die entfernt werden muss, was nicht jeder Patch berücksichtigt.
Diese Module sollten nach einem Scann im Upgrade Status Report nun nicht mehr als inkompatibel gemeldet werden.
3. Gepatchte Module erzeugen beim Composer Update eine Fehlermeldung
Diese Fehlermeldung sieht z.B. so aus
- drupal/superfish dev-1.x requires drupal/core ^8 || ^9 -> satisfiable by drupal/core[8.0.0, ..., 8.9.20, 9.0.0, ..., 9.5.3].
In dem Fall beschäftige Dich mit Lenient.
Das lenient composer plugin erlaubt, eine Liste von Paketen anzugeben, bei denen die Versionsbeschränkung außer acht gelassen werden.
composer config --merge --json extra.drupal-lenient.allowed-list '["drupal/superfish"]'
Hier muss ich auf die entsprechende Webseite verweisen.
In meinem Fall kam es nicht so weit, weil meine Wunschmodule dann alle in einer Drupal 10 kompatiblen Version vorlagen.
https://www.drupal.org/docs/develop/using-composer/using-drupals-lenien…
4. Manche Pakete benötigen PHP 7.* auf der Konsole
Wir bekommen eine Fehlermeldung beim Coomposer Update, dass manche Pakete eine alte PHP Version benötigen. Stellen wir zurück auf Drupal 7.*, dann scheitert das Update wegen anderen Paketen, die PHP 8.1 als Minimum benötigen.
In diesem Fall kann der Flag --ignore-platform-req=php helfen, wie hier beschrieben.
https://stackoverflow.com/questions/66368196/reference-composer-error-y…
5. Weitere Fehler
Hier hilft nur die Google Suche und viel Versuch+Irrtum mit Backups.