Eine bestehende Drupal-8 Website auf die aktuelle Version des Drupal-Composer Projekts „mergen“, um diese Website in Zukunft mit Composer upzudaten. Unterwegs werden auch ein paar Änderungen eingeführt, die das Umstellen der Umgebungen (Lokaler Webserver und Entfernter Webserver beim Hoster) vereinfachen. Eine funktionierende lokale Webserver-Umgebung wird vorausgesetzt: LAMP, WAMP, Virtualbox oder ähnliches. Hier gibt es zahlreiche Lösungen.
Ich persönlich habe mir auf meinem Mac parallel zum „eingebauten Webserver“, dessen Konfiguration durch System-Updates verändert wird, mit homebrew eine Umgebung aufgebaut. Für die lokale Ablage der Websites nutze ich ein Synology NAS mit genügend Terabytes Plattenspeicher für sehr viele Websites. Die Variante, eine lokale Webserver-Umgebung direkt auf dem NAS zu etablieren, habe ich getestet und verworfen. Die Variante mit homebrew ist flexibler und kann jederzeit an Erfordernisse angepasst werden.
Vorteile von Composer
Composer ist eine Art „Paketmanager“ für PHP-basierte Projekte, wie z.B. Drupal und viele andere. Diese nutzen Bestandteile anderer Projekte, um best. Funktionen bereitzustellen. So müssen die Programmierer nicht immer das Rad neu erfinden und es können sich Standards entwickeln. Anstatt wie früher Drupal von drupal.org als „Tarball“ (gepacktes Archiv) runterzuladen, erzeugt man einfach ein „Drupal-Projekt“. Wenn eine Website erstmal auf den Stand des aktuellen Drupal-Composer Projekts gebracht ist, ergeben sich hier vor allem Geschwindigkeitsunterschiede beim Updaten auf neue Drupal-Versionen. Auch das Installieren / Entfernen von Modulen, JavaScript Libraries etc. ist in Zukunft ein einfacher Befehl auf Kommandozeile oder ein paar Mausklicks in ComposerCat. Composer lebt hier: https://getcomposer.org/ Normalerweise wird Composer via Shell (Kommandozeile) bedient, es gibt aber auch ein nettes Tool namens ComposerCat, mit dem man eine grafische Oberfläche hat. Diese lebt hier: https://www.getcomposercat.com/
Begrifflichkeiten
Website-Dateien: Alle Dateien, die zu einer Website gehören. Einfach alles.
Drupal-Dateien: Alle Dateien, die zu Drupal selbst gehören und z.B. durch Installer oder Composer erzeugt werden.
User-Dateien: Alle Dateien, die User zum Inhalt der Website hinzugefügt haben, z.B. Bilder, Dokumente etc. Normalerweise liegen diese unter /sites/default/files.
Drupal-DB: Die verwendete Drupal-Datenbank. Ich gehe hier von einer einfachen Installation mit 1 Datenbank für 1 Website aus. Bei Verwendung von mehreren Datenbanken entsprechend verfahren.
Projekt-Name = Projekt-Ordner = Projekt: Vorgeschlagen wird, den Domain-Namen ohne .tld (Top-Level Domain) als Projekt-Namen / Ordner-Namen zu verwenden, für eine unfallfreie Zuordnung zwischen Projekt und Website. Aus [meine-domain.de] wird also das Projekt [meine-domain].
Unterschied Drupal Tarball zu Composer-Projekt
Diese Tabelle zeigt grob die wichtigsten Unterschiede zwischen Tarball und Composer-Projekt. Zu beiden gehören noch weitere Dateien, hier sind nur die wichtigsten aufgeführt.
| „Tarball“ (Drupal runterladen und entpacken) | Composer (Mit Composer erzeugte Struktur) |
|---|---|
\{Projekt-Ordner\} = WebRoot | \{Projekt-Ordner\} |
.htaccess | .env.example |
autoload.php | composer.json |
composer.json | composer.lock |
composer.lock | drush/ |
core/ — Drupal selbst | load.environment.php |
index.php | scripts/ |
modules/contrib/custom/ | vendor/ |
profiles/ | web/ — WebRoot |
robots.txt | .htaccess |
sites/default/files/ | autoload.php |
settings.php | core/ — Drupal selbst |
themes/contrib/custom/ | index.php |
update.php | libraries/ — JavaScript |
vendor/ | modules/contrib/custom/ |
profiles/contrib/custom/ | |
robots.txt | |
sites/default/files/ | |
settings.php | |
themes/contrib/custom/ | |
update.php |
Nach diesen Vorab-Klärungen nun direkt zum Workflow.
Auf dem Webserver
Diese Vorgänge werden auf dem Webserver durchgeführt.
| Vorgang | Beschreibung | Zeit-Schätzung |
|---|---|---|
| Website-Dateien Backup | Alle Dateien, die zur Website gehören, sichern. Über ein Tool des Hosters oder manuell in der Shell mit gzip oder ähnlichem. Bei Hosteurope z.B. einfach mit „Backup on the fly“ – auch zusammen mit Drupal-DB in einem Rutsch. | 15 min. |
| Drupal-DB Backup | Die für die Website verwendete Datenbank sichern. Mit Tool des Hosters, phpMyAdmin oder ähnlichem. | 5 min. |
Die gesicherten Dateien mit den Backups der Dateibasis und der Datenbank lokal runterladen, z.B. per FTP.
Lokal
Diese Vorgänge werden lokal durchgeführt.
| Vorgang | Beschreibung | Zeit-Schätzung |
|---|---|---|
| Projekt-Ordner anlegen | Ordner erzeugen: \{Projekt-Ordner\}. Hierin weitere Unter-Ordner erzeugen, die wir gleich brauchen werden: assets/, backup/, db-dump/, favicons/, config/, sync/, private/ | 2 min. |
| Backups ablegen | Das \{Website-Dateien Backup\} in [assets/backup/] und das \{Drupal-DB Backup\} in [assets/db-dump/] ablegen. \{Website-Dateien Backup\} auspacken. \{Drupal-DB Backup\} in lokales SQL-Tool importieren. Name der DB gleich \{Projekt-Name\} | 10 min. |
Composer-Projekt erzeugen:
In einer Shell (Kommandozeile) mit folgendem Befehl ein aktuelles Drupal-Composer Projekt im \{Projekt-Ordner\} anlegen:
cd \{Projekt-Ordner\}
composer create-project drupal-composer/drupal-project:8.x-dev my_site_name_dir --no-interaction --no-dev
Im Detail:
composer— der Paketmanager composer(.phar)create-project— leg Drupal-Projekt andrupal-composer/drupal-project:8.x-dev— Mindest-Stabilität: devmy_site_name_dir— tmp. Ordner, wird nicht lange gebraucht--no-interaction— automatischer Lauf--no-dev— pot. unsichere Entwicklungsdinge nicht mit installieren. Wer keinen eigenen Sourcecode für Drupal, z.B. in Form von Modulen, erzeugt, benötigt die Development-Dinge nicht. Die „dev“ Pakete sollten nur lokal, nicht aber auf dem Produktions-/Live-Server verwendet werden.
Manuelles „mergen“:
Den Inhalt von [my_site_name_dir] eine Ordner-Ebene höher ziehen (inklusive der „unsichtbaren“ Punkt-Dateien), damit die von Composer erzeugten Dinge direkt unter \{Projekt-Ordner\} liegen. Der jetzt leere Ordner [my_site_name_dir] kann gelöscht werden.
2 Datei-Browser-Fenster öffnen:
Ansicht 1: \{Projekt-Ordner\}/assets/backup/*
Ansicht 2: \{Projekt-Ordner\}
Im Folgenden meint \{Backup\} die Ansicht auf \{Projekt-Ordner\}/assets/backup/*.
Alle Dinge aus dem \{Backup\} an ihre jeweilige, korrekte Position in der Drupal Dateistruktur schieben. Siehe unten „Drupal Dateistruktur“.
composer.json:
Alle verwendeten Module in composer.json eintragen. Folgende Varianten sind möglich: Texteditor, Shell mit composer require drupal/namedesmoduls:version, ComposerCat.
composer update:
Mit dem Ausführen von composer update wird alles auf den aktuellen Stand gebracht. Drupal selbst, alle verwendeten (und in composer.json eingetragenen) Module sowie Abhängigkeiten im vendor/ Verzeichnis uvm. Sollte das updaten Probleme bereiten, einfach den Ordner vendor/ löschen. Dieser wird automatisch neu erzeugt und bestückt.
Settings:
Die Datei \{Projekt-Ordner\}/.env mit Informationen aus den Settings-Dateien des \{Backup\} füllen. \{Projekt-Ordner\}/sites/default/settings/* überprüfen, ggf. nach Wunsch ändern. Siehe „Drupal Settings“ Abschnitt unten.
Lokal Web:
Anschließend die Website lokal aufrufen, update.php ausführen und ggf. Fehlermeldungen fixen. Es wird empfohlen, die Einstellungen für Trusted Hosts in /sites/default/settings/settings.shared.php vorzunehmen.
Fertig. Die vorherige Website ist jetzt auf das aktuelle Drupal-8-composer Projekt umgestellt und kann hochgeladen werden. Von der lokalen (jetzt aktuellen) Datenbank einen Export ziehen und auf dem Webserver entsprechend importieren. Auf dem Webserver muss nach dem Hochladen der Dateien und der Datenbank nur in der Datei .env der Schalter von „local“ auf „prod“ umgestellt werden.
Drupal-Dateistruktur
\{Projekt-Ordner\}/.editorconfig.env— hier stehen geheime Dinge wie DB-Zugang etc..env.example.gitattributes.gitignore— Wichtige Datei, was soll nicht durch git verwaltet werden.travis.ymlassets/backup/db-dump/
composer.jsoncomposer.lockconfig/sync/
drush/— (Drush-Zeugs)LICENCEload.environment.phpphpunit.xml.distprivate/— (für “private” Dateien, die nicht übers Web erreichbar sein sollen)README.mdscripts/composer/— (composer-Zeugs)vendor/— (alle PHP-Projekte, die Drupal-8 bezieht)web/← auf diesen Ordner soll später die Domain zeigencore/— (Drupal-8 mit all dem, was es ausmacht)index.php— Diese wird vom Webserver aufgerufen und ist der Startpunkt der Websitelibraries/— (Verzeichnis für JavaScript-Dinge)modules/custom/— Module, die selbst gebaut oder gekauft sindcontrib/— Module von drupal.org
profiles/robots.txtsites/default/default.services.ymldefault.settings.phpfiles/— (gecachte Drupal Dateien und\{User-Dateien\})php/— twig-Cache Dateien, werden autom. erzeugt
services.ymlsettings/settings.local.phpsettings.prod.phpsettings.shared.php
settings.php— Includiert[settings/settings.shared.php]
development.services.ymlexample.settings.local.phpexample.sites.php
themes/custom/— Themes, die selbst gebaut oder gekauft sindcontrib/— Themes von drupal.org
update.phpweb.config— Datei für IIS Webserver
Drupal Settings
Anstatt die Datei /sites/default/settings.php jedesmal anzupassen, wenn die Website zwischen “lokal” und “Server” verschoben wird, und um mehr Sicherheit für die verwendeten Datenbank-Zugänge etc. zu bieten, werden diese sensiblen Daten jetzt in der Datei .env festgehalten, die sich außerhalb des Webroots (/web) befindet, so dass sie für den Webbrowser nie erreichbar ist.
Als 2. Verbesserung wurde die Struktur für die Settings überdacht und Folgendes ist entstanden: /sites/default/settings.php enthält nur den Aufruf der Datei /sites/default/settings/settings.shared.php. Je nachdem, was in den Wert von APP_ENV in der .env geschrieben wird \{local, prod\}, werden entweder /sites/default/settings/settings.local.php ODER /sites/default/settings/settings.prod.php nachgeladen.
Hiermit ist nun eine saubere Trennung zwischen Umgebungen (Environments) möglich. Diese Idee habe ich bei blog.netgloo.com aufgeschnappt und fand es prima. Die Struktur ist jederzeit erweiterbar. Da ich den Tmp-Pfad für die jeweilige Umgebung in der jeweiligen Settings-Datei vorgebe, lösche ich in der Website im Backend den Wert unter /admin/config/media/file-system. Das ist problemlos möglich.
Datei /sites/default/settings.php:
<?php include __DIR__ . '/settings/settings.shared.php';