Drupal
Drupal ❤ Composer
Man muss nicht lange suchen, um in Foren Beiträge von auch langjährigen Drupal 7 Nutzern und Sitebuildern zu finden, die Drupal 8 wegen der starken Integration von Composer keine gute Zukunft attestieren. Vor allem für Amateur-Admins, die vielleicht im Alleingang Seiten von kleineren Projekten oft auf ehrenamtlicher Basis betreuen, scheint es eine besondere Herausforderung zu sein. Konnten sie bisher auch ohne großartige Programmierkenntnisse Dank der unzähligen Contrib Module für Drupal 7 sehr komplexe Websites fast alleine mit der Maus entwickeln, schadet für Drupal 8 zumindest ein kleiner Rucksack voller PHP Skills und keine Angst vor einer Linux Shell nicht.
Sitzt man als Programmierer in einer "Web Bude", raunzt man anfangs zwar darüber, dass für Drupal 8 alles neu gelernt werden muss, irgendwann ist das Team aber umgesattelt und denkt nicht zurück.
Wer aber vielleicht pro bono ein Projekt in seiner Freizeit betreut, hat oft nicht die Zeit und Ressourcen, eine problemlos funktionierende Seite einzustampfen und von Grund auf neu aufzubauen. Und das ganze in einem Framework, das unter der Haube nur am Rande mit dem alten zu tun hat. Ich versteh, dass diese Leute in Foren Drupal 8 haten. Für D7 genügt ein kleiner Webspace, der alleine über FTP bespielt wird, D8 will von Composer und Drush über eine Shell bedient werden oder fordert zumindest eine lokale Entwicklungsumgebung, aus der auf den Server gesynct wird.
Fakt ist aber, Composer, Drush und Drupal 8 zu "lernen", macht sich für jeden Entwickler und Site builder bezahlt; du bist am Ende ein besserer Entwickler und hast ein mächtiges Tool, um State of the Art Projekte abzuliefern. Die Auslagerung der Konfiguration in versionierbare Files ist ein Traum, vor allem wenn im Team gearbeitet und in kurzen Zyklen releast wird. Viel stärker als unter Drupal 7, kommen in 8 eine Vielzahl an Open Source Projekten zu Einsatz. Die Frameworks und Techniken, die man sich unter Drupal 8 aneignet, sind also auch abseits der Drupal Welt nützlich.
Für all jenen, die sich vielleicht zwar über das End-Of-Life von Drupal 7 im Herbst 2021 ärgern, aber selbstverständlich trotzdem auf Drupal 8 umsteigen, soll dieser kleine Überblick über die Administration von Drupal Websites mit Composer eine schnelle Einführung sein.
Dieser Text wurde im Zuge einer Drupal Schulung in Wien als Handout verteilt.
Allgemeines
Composer ist ein Paketmanager für PHP Projekte. Er erlaubt die Installation kompletter Anwendungen oder von einzelnen Paketen, Bibliotheken, etc. Ähnlich wie Playstore oder Applestore am Handy. Composer ist keine Eigenheit von Drupal sondern wird regulär für die Verwaltung von PHP Projekten verwendet.
Wichtig zu verstehen ist das Zusammenspiel von Composer und Drush bei der Administration einer Drupal Website. Composer „kümmert“ sich ausschließlich um die Dateien, aus denen ein Modul, Theme oder eine andere Komponente besteht. Composer kümmert sich darum, welche Versionen eines Pakets/Moduls installiert werden dürfen und führt nach der Installation - je nach Konfiguration - Operationen wie das Anwenden von Patches aus. Composer „spricht“ aber nicht selbst mit der Drupal Datenbank.
Um mit Composer installierte Erweiterungen in Drupal nutzen zu können, muss das Modul über das Drupal Backend oder Drush (drush en <module name>) installiert werden.
Wird ein Modul mithilfe von Composer aktualisiert, muss Drupals update.php oder drush updb ausgeführt werden. So kann Drupal die notwendigen Aktualisierungen in der Datenbank durchfühen.
Prüfen ob Composer installiert ist
composer --version
Wenn nicht, muss die Composer executable auf den Server kopiert und - wenn es Composer global verwendet werden soll - installiert werden.
Anweisungen dazu unter: https://getcomposer.org/download/
Eine Drupal Seite mit Composer installieren
Ausführliche Dokumentation und Anleitung:
In der Drupal Dokumentation unter Using Composer to Install Drupal and Manage Dependencies.
Die Installation der der Drupal Seite kann über folgenden Befehl in der Kommandozeile gestartet werden.
composer create-project drupal/recommended-project <Name des Verzeichnisses>
Nach der Installation steht die neue Drupal Seite unter <Name des Verzeichnisses> zur Verfügung. Befolgen Sie danach die Anweisungen am Bildschirm. Vor allem das core-project-message Paket sollte entfernt werden:
composer remove drupal/core-project-message
Danach drush (Drupal Shell) installieren. Damit kann eine Drupal Seite über die Commandline administriert werden.
composer require drush/drush
Prüfen ob Drush richtig installiert ist und die Seite findet:
drush status
Der Befehl zeigt Informationen zur Datenbank, zu den Verzeichnissen der Drupal Instanz usw.
Bevor der Setup-Assistent gestartet wird, sollte sichergestellt werden, dass der Webserver-Benutzer (z. B. httpd, www-data oder apache) im Unterverzeichnis ./web/sites Schreibberechtigungen hat. So ist sichergestellt, dass der Assistent alle notwendigen Einstellungen vornehmen kann.
cd public_html/web
chmod -R ugo+w ./sites
ACHTUNG: Vergessen Sie nicht, nach Abschluss der Installation die Schreibberechtigungen wieder zu entfernen und nur im files Unterverzeichnis den Webserver Schreibberechtigungen einzuräumen.
Danach kann der Setup Assistent gestartet werden:
http://www.adressederseite.at/core/install.php
Drupal 8 Verzeichnisstruktur
Drupal 8 hat eine etwas andere Verzeichnisstruktur als Drupal 7. Im Projektverzeichnis (z. B. public_html) befindet sich ein weiterer Ordner ./web. Das ist das Stammverzeichnis der Website, der Webserver sollte keine Verzeichnisse höher als ./web nach außen zeigen. Ein Administrator muss Apache so umkonfigurieren, dass z. B. public_html/web als Docroot (Stammverzeichnis der Website) verwendet wird. Bsp. Docroot /var/www/sites/meinewebsite/public_html/web .
Module und Themes
Module und Themes werden nicht mehr unter sites/all/themes bzw. sites/all/modules installiert, sondern finden sich direkt in /web/modules bzw. /web/themes.
Anders als unter Drupal 7 sollte im Verzeichnis für Module und Themes mehr Ordnung herrschen. Auch wenn es weiterhin möglich ist, ein Modul einfach unter web/modules zu installieren, sollte zumindest zwischen offiziell verfügbaren Modulen und selbst programmierten Erweiterungen unterschieden werden.
-
Offizielle Module: /web/modules/contrib/<modul name>
-
Selbst programmierte Erweiterungen: /web/modules/custom/<module name>
Gleiches gilt auch für Themes
-
Offizielle Themes: /web/themes/contrib/<theme name>
-
Selbst programmierte Erweiterungen: /web/themes/custom/<theme name>
Files und settings.php
Das Verzeichnis für im Backend hochgeladene Dateien sowie die Haupt-Konfigurationsdatei settings.php befinden sich weiterhin im Verzeichnis public_html/web/sites/default/files/ bzw. public_html/web/sites/default/settings.php . Wie unter Drupal 7 muss sichergestellt werden, dass der Webserver in diesen Verzeichnissen schreiben darf.
Drupal Module mit Composer und Drush verwalten
Es ist auch weiterhin möglich, Module, Themes und Libraries manuell zu installieren. Der Ablauf ist gleich wie bereits unter Drupal 7.
Der Vorteil von Composer ist, dass vor der Installation geprüft wird, ob Module kompatibel sind. Updates können über zwei kurze Befehle auf der Kommandozeile erledigt werden und müssen nicht über viele Klicks im Backend erfolgen.
Der Nachteil ist, Composer benötigt eine Weile, bis man sich daran gewöhnt hat. Da das System umfassend frei konfigurierbar ist, ist das Tool mit einer steilen Lernkurve verbunden. Fehlermeldungen sind für Anfänger (und leider auch Fortgeschrittene) nicht ganz einfach zu deuten. Google Recherchen liefern aber meist rasche Hilfe.
Ein Modul installieren
Module können weiterhin einfach über die Drupal Website gesucht werden. Composer bietet aber auch eine Möglichkeit, ein Modul direkt auf der Kommandozeile zu suchen.
Als Beispiel Installieren wir das Modul Admin Toolbar (https://www.drupal.org/project/admin_toolbar)
Module suchen und verfügbare Versionen finden
composer search admin*tool* bzw.
composer show --all drupal/admin*tool*
available:
drupal/admin_menu_toolbar
drupal/admin_toolbar
drupal/admin_toolbar_content_languages
Um eine Liste aller verfügbaren Versionen dieses Moduls zu zeigen, wird Composer Show mit dem vollen Namen des Pakets ausgeführt:
composer show --all drupal/admin_toolbar
name : drupal/admin_toolbar
descrip. : Provides a drop-down menu interface to the core Drupal Toolbar.
keywords : Drupal, Toolbar
versions : 2.x-dev, * 2.0.0, 2.0.0-beta2, 2.0.0-beta1, 1.x-dev
Ein Modul installieren
Beim Installieren von Modulen wird ein Eintrag für das gewünschte Modul in der Konfigurationsdatei composer.json abgelegt. Neben dem Namen des Moduls findet sich dort eine Versionsnummer oder eine Version Constraint. (Siehe weiter unten Version Constraint.)
composer require drupal/admin_toolbar (=aktuellste Version installieren)
composer require drupal/admin_toolbar:2.0.0 (= bestimmte Version installieren)
Das Modul wird automatisch unter web/modules/contrib/admin_toolbar installiert.
Composer zeigt, welche Version des Moduls installiert wird: Using version ^2.0 for drupal/admin_toolbar
Nach diesem Schritt ist das Modul verfügbar, aber noch nicht in Drupal installiert. Es kann entweder über das Drupal Backend oder über Drush aktiviert werden.
Im Backend unter www.meineseite.at/admin/modules
Mit dem Drush Befehl: drush en admin_toolbar
Prüfen ob ein Modul installiert ist
Mit Composer kann lediglich geprüft werden, ob das Modul im Webspace verfügbar ist:
composer show drupal/admin_toolbar
Der Befehl liefert eine Reihe an Informationen zu diesem Paket. Name, Beschreibung, Versionen, Lizenzen, usw. Er zeigt aber nicht, ob das Modul in Drupal aktiviert wurde.
Um zu prüfen, ob das Modul admin_toolbar aktiviert ist, wird Drush verwendet:
drush pml | grep admin_toolbar
Administration Admin Toolbar (admin_toolbar) Enabled 8.x-2.0 Administration Admin Toolbar Extra Tools (admin_toolbar_tools) Disabled 8.x-2.0
Die Ausgabe zeigt, dass das Modul admin_toolbar in der Version 2.0 installiert/aktiviert ist. Das Modul admin_toolbar_tools hingegen ist nicht aktiviert.
Ein Modul entfernen
Das Entfernen eines Moduls erfolgt in zwei Schritten:
-
Das Modul aus Drupal deinstallieren
-
Das Modul bzw. dessen Dateien mit Composer entfernen
Achtung: Wird darauf vergessen, das Modul vor der Entfernung aus Drupal zu deinstallieren, erscheinen im Backend der Drupal Seite Fehlermeldungen, die darauf hinweisen, dass ein Modul nicht im dafür vorgesehenen Pfad gefunden wurde. Um den Fehler zu beheben, müssen Sie das Modul mit Composer neuerlich installieren, über Backend oder mit Drush deinstallieren und danach erst die Dateien des Moduls löschen.
1. Das Modul deinstallieren
drush pmu admin_toolbar
[success] Successfully uninstalled: admin_toolbar
2. Das Modul mit Composer entfernen
composer remove drupal/admin_toolbar
Package operations: 0 installs, 0 updates, 1 removal
- Removing drupal/admin_toolbar (2.0.0)
Drupal Updates mit Composer durchführen
Verfügbare Aktualisierungen anzeigen
composer outdated
consolidation/log 1.1.1 2.0.0 Improved Psr-3 / Psr\Log logger based on Symfony Console components.
consolidation/output-formatters 3.5.0 4.1.0 Format text by applying transformations provided by plug-in formatters.
consolidation/robo 1.4.11 2.0.0 Modern task runner
container-interop/container-interop 1.2.0 1.2.0 Promoting the interoperability of container objects (DIC, SL, etc.)
Package container-interop/container-interop is abandoned, you should avoid using it. Use psr/container instead.
dflydev/dot-access-data v1.1.0 v2.0.0 Given a deep data structure, access data by dot notation.
Der Befehl zeigt eine Reihe von Modulen, die nicht direkt mit Drupal zu tun haben. Drupal selbst basiert auf einer großen Zahl unterschiedlicher, Open Source Pakete, die alle zusammen über Composer verwaltet werden. Composer verwaltet diese für uns, es ist idR nicht notwendig, selbst diese vielen Pakete zu überblicken und zu verwalten. Beim Update von Drupal Core werden die notwendigen Pakete im Hintergrund aktualisiert.
Aktualisierungen nur für Drupal Pakete/Module anzeigen
Um eine übersichtlichere Liste der Module, die direkt Drupal betreffen, zu erhalten, wird die Kategorie mit angegeben:
composer outdated drupal/*
drupal/admin_toolbar 1.27.0 2.0.0 Provides a drop-down menu interface to the core Drupal Toolbar.
Übrig bleibt ein einziges Modul, für das Updates verfügbar sind. Im Beispiel könnte das Modul admin_toolbar von Version 1.27.0 auf 2.0.0 aktualisiert werden.
Ein Modul mit Composer aktualisieren
Updates erfolgen in zwei Schritten
-
Modul über Composer aktualisieren
-
Modul Updates in Drupal ausführen (update.php oder drush updb)
1. Modul über Composer aktualisieren
composer update drupal/admin_toolbar
Dieser Befehl aktualisiert ein Modul auf die neueste Version, aber ...
Wenn der Befehl composer outdated drupal/* aktualisierbare Module zeigt, aber der Update Befehl die Meldung Nothing to install or update liefert, sind in vielen Fällen die Version Constraints, also Einschränkungen dafür, welche Versionen automatisch bei einem Update installiert werden dürfen, die Ursache. (Siehe dazu Absatz Version Constraints weiter unten.)
Prüfen warum das Modul nicht aktualisiert werden kann:
composer why-not drupal/admin_toolbar
drupal/recommended-project - requires drupal/admin_toolbar (^1.0)
Im Composer Script werden sogn. Version Constraints gesetzt. Eine Zeile wie
"drupal/admin_toolbar": "^1.0",
in der Datei composer.json bedeutet, dass der Update-Befehl Versionen zwischen 1.0 bis 1.99+ installieren darf. Wird wie im Beispiel auf Version 2.0.0 aktualisiert, liefert der Update-Befehl einen Fehler:
Nothing to install or update
Um das Modul dennoch zu aktualisieren, muss beim Update eine Version ausdrücklich „bestellt“ werden. Das kann entweder eine konkrete Version 2.0.0 oder eine allgemein Version ^2 sein. ^2 würde wiederum bedeuten, alle Versionen zwischen 2.0 bis kleiner als 3.0 dürfen bei einem Update „mitgenommen“ werden.
composer require drupal/admin_toolbar:^2
Package operations: 0 installs, 1 update, 0 removals
- Updating drupal/admin_toolbar (1.27.0 => 2.0.0)
2. Modul Updates in Drupal ausführen
Im ersten Schritt wurden „nur“ die Dateien des Moduls über Composer aktualisiert. Jetzt muss auch Drupal, genauer gesagt die Datenbank dahinter, über das neue Modul benachrichtigt werden. Neue Modulversionen können Änderungen an den Datenbanktabellen benötigen, diese werden bei diesen Updates ausgeführt.
Updates können über das Drupal Backend (update.php) oder mittels Drush ausgeführt werden (drush updb).
Version Constraints
Was irgendwie kompliziert klingt, hat einen einfachen Hintergrund. Theoretisch könnte bei jedem Update die konkrete Versionsnummer zB. 1.2.3 angegeben werden. In der Regel lassen sich aber Drupal Module bis zum nächsten „großen Versionssprung“, zB. zwischen 1.2.3 bis kleiner 2.0 ohne große Kopfzerbrechen aktualisieren. (Dafür übernehme ich aber keine Gewähr!) Version Constraints erlauben es, eine Bandbreite von Versionen bei Updates zu erlauben.
Ein Beispiel:
drupal/admin_toolbar:1.2.3 definiert Version 1.2.3.
drupal/admin_toolbar:^1.2 hingegen bedeutet, dass jede Version größer oder gleich 1.2.0 bis kleiner als 2.0 installiert werden darf.
Versuchen wir an dieser Stelle mit composer update drupal/admin_toolbar auf Version 2 zu aktualisieren, erhalten wir den Fehler ‚Nothing to install or update‘.
Um trotz der Versionsbeschränkung ^1.2 auf Version 2 zu aktualisieren, muss ausdrücklich der „große Versionssprung“ verlangt werden:
composer require drupal/admin_toolbar:2.0
Troubleshooting
Tritt während der Verwendung von Composer ein Fehler auf, werden die Änderungen rückgängig gemacht und eine Fehlermeldung gezeigt:
Häufige Fehler
Installation failed, reverting ./composer.json to its original content. [RuntimeException]
Could not delete /var/www/sites/bvoe/composer_workshop/web/sites/default/default.services.yml:
Der Fehler deutet darauf hin, dass Composer keine Erlaubnis hat, die Datei default.services.yml zu verändern. Die Berechtigungen der Datei oder des übergeordneten Verzeichnisses müssen korrigiert werden. IdR. Hat der Benutzer keinen Schreibzugriff auf sites/default/files, wenn dieser Fehler auftritt.
chmod ug+w /pfad/zum/verzeichnis/web/sites/default
[InvalidArgumentException]
Package admin_toolbar not found
Der Fehler weißt darauf hin, dass Composer das gewünschte Modul/Paket nicht finden kann. Ursache dafür ist häufig ein falsch geschriebener Name eines Moduls, oder dass vergessen wurde, den Namen der Paket-Kategorie anzuführen.
Composer findet alle Drupal Module unter der Kategorie drupal/<Paketname>.
Der Befehl composer show admin_toolbar liefert einen Fehler, hingegen composer show drupal/admin_toolbar findet das gewünschte Paket.
Kleines Composer Cheat Sheet
Alle Composer Befehle
Alle installierten Pakete anzeigen
- composer show
Alle verfügbaren Pakete anzeigen
- composer show –all
- composer show –all drupal/*
- composer show –all drupal/*toolbar =>
Ein Paket suchen
- composer search teildesnamens*nocheinteil*nocheinteil
z. B. composer search admin*tool* => drupal/admin_toolbar
Prüfen warum ein Paket nicht installiert werden kann
composer why-not drupal/admin_toolbar
Kleines Drush Cheat Sheet
Alle verfügbaren Drush Befehle zeigen
- drush
- drush | grep <name der gesuchten funktion>
Beachten Sie: Module können den Funktionsumfang von Drush erweitern und neue Befehle zur Verfügung stellen.
Drupal Cache neu aufbauen
- drush cr
Drupal Modul installieren
- drush en <module name>
Drupal Modul deinstallieren
- drush pmu <module name>
Liste der Installierten Drupal Module zeigen
- drush pml
Liste einschränken
- drush pml | grep <module name>
Nach Update eines Moduls Drupal Datenbank aktualisieren
- drush updb
Liste der nötigen Datebankaktualisierungen anzeigen
- drush updbst
Prüfen ob neue Sicherheitsupdates verfügbar sind
- drush sec
[success] There are no outstanding security updates for Drupal projects.