Composer zu einer bestehenden Website hinzufügen

Vereinfacht in Drupal 8.8.0

Hinweis: Wenn Sie Ihr Projekt mit Drupal Version 8.8.0 oder neuer begonnen haben, verwendet Ihre Website bereits die korrekte Verzeichnisstruktur und ist bereit für die Umstellung auf Composer.

Diese Seite ist eine Schritt-für-Schritt-Anleitung, wie Sie manuell Composer-Unterstützung zu einer bestehenden Website hinzufügen, die zuvor ohne Composer installiert wurde. Diese Anleitung ist für Sie, wenn Sie Drupal 8 manuell aus einem Archiv installiert haben oder eine veraltete Composer-Vorlage wie drupal/drupal verwendet haben.

Für Websites, die mit Drupal 8.8.0 oder neuer erstellt wurden

Selbst wenn Sie Drupal 8.8.0 aus einem Archiv installiert haben, ist Composer bereits vorinstalliert. Daher sollten Sie Ihre Website mit Composer verwalten können, ohne weitere Umstellungsschritte vornehmen zu müssen.

Für Websites, die vor Drupal 8.8.0 erstellt wurden

Die composer.json Datei, die mit Archiven vor Drupal 8.8.0 von https://www.drupal.org/download mitgeliefert wurde, war nicht für eine Composer-gesteuerte Website vorgesehen.

Wenn Sie von manueller Verwaltung zu Composer für die Installation und Aktualisierung des Drupal-Cores und zusätzlicher Module wechseln möchten, müssen Sie zuerst die composer.json Ihrer Website anpassen.

Typische Composer-Fehlermeldungen, die auf eine fehlerhafte composer.json hinweisen können:

Nothing to install or update (even though updates exist) 

Installation request for drupal/drupal No version set (parsed as 1.0.0) -> satisfiable by drupal/drupal[No version set (parsed as 1.0.0)]. 

don't install drupal/core 8.x.x | remove drupal/drupal No version set (parsed as 1.0.0) 

Your requirements could not be resolved to an installable set of packages.

Manchmal lassen sich Composer-Vorlagenprobleme beheben, indem man die composer.lock und das vendor-Verzeichnis löscht, bevor man Composer-Updates ausführt. Doch die Umstellung einer bestehenden Drupal 8 Website auf ein Composer-Projekt gemäß dem in der Drupal 8 Installationsanleitung empfohlenen Composer-Template (3.5. Composer zur Dateiverwaltung) ist eine nachhaltigere Lösung für Update-Probleme.

Die Tools gocomposer und composerize drupal versuchen, den Umstellungsprozess zu automatisieren, aber eine manuelle Umstellung ist auch für größere Websites einfach und zeitlich nicht aufwendig.

Am Ende hat Ihr Projekt die empfohlene Verzeichnisstruktur. Composer-Konfiguration (composer.json, composer.lock, etc.), Drush und das vendor-Verzeichnis liegen außerhalb Ihres webroot. Ihr ursprüngliches webroot enthält einen neuen Ordner web/, in dem sich die eigentliche Website befindet. Wenn Ihr Projekt aktuell eine andere Verzeichnisstruktur nutzt, müssen Sie Ihre Webserverkonfiguration anpassen, damit sie auf den neuen web/-Ordner zeigt. Darauf gehen wir später ein.

Kurzfassung (TL;DR)

1. Installieren Sie eine neue Drupal-Site mit dem aktuellen Composer-Template in einem neuen Verzeichnis.
2. Kopieren Sie alle benutzerdefinierten Themes, Module, Dateien und Einstellungen in das neue Projekt. (Überprüfen Sie die Verzeichnisstruktur genau.)
3. Übertragen Sie die Einstellungen in das neue Projekt.
4. Fügen Sie alle zusätzlichen Module zur neuen composer.json hinzu und führen Sie composer install aus.
5. Datenbank aktualisieren und Cache leeren (drush updb; drush cr)
6. Aktualisieren Sie die Webserver-Konfiguration.

VOLLSTÄNDIGE ANLEITUNG

Diese Anleitung setzt voraus, dass Ihre bestehende Website im Verzeichnis /var/www/sites/html/ liegt und Sie eine neue Site unter /var/www/sites/new_html/ erstellen. Passen Sie die Pfade für Ihre tatsächlichen Verzeichnisse an.

Bevor Sie beginnen

Wenn Sie den alten Drupal-Core und contrib-Module Ihrer Website „komponieren“ wollen, sind diese wahrscheinlich nicht in den aktuellsten Versionen. Folgen Sie blind dieser Anleitung, werden Core und Module auf die neuesten Versionen aktualisiert. Das ist oft gewünscht, bedenken Sie aber die Konfiguration Ihrer Website. Gibt es Gründe, nicht alle Core- oder Modulversionen zu aktualisieren? Möglicherweise beruht Ihre Installation auf einer älteren Bibliotheks- oder Modulversion und sollte nicht aktualisiert werden.

Wenn Sie alles auf die neueste Version aktualisieren wollen, folgen Sie einfach der Anleitung und beheben Sie anschließend mögliche Probleme. Nach dem Update treten wahrscheinlich Fehler oder Warnungen auf, die mit neuen Modulversionen zusammenhängen. Suchen Sie in solchen Fällen online nach Lösungen oder Patches.

Wenn Sie Ihre ursprünglichen Versionen behalten und später mit Composer aktualisieren möchten, stellen Sie sicher, dass Sie dieselben Core- und Modulversionen wie auf der alten Website installieren. Schauen Sie in die composer create-project Anleitungen, wie Sie eine bestimmte Core-Version oder bestimmte contrib-Modul-Versionen installieren. Geben Sie diese Versionen bei composer create-project oder composer require an (z. B. composer require vendor/package:version).

1. Neue Drupal-Site installieren

Erstellen Sie ein neues Drupal-Projekt mit dem Template drupal/recommended-project:

cd /var/www/sites
composer create-project drupal/recommended-project:~8.8.0 new_html --stability dev --no-interaction

Dies erzeugt im aktuellen Verzeichnis den Ordner new_html/, der die Verzeichnisse vendors und web (webroot) sowie composer.json und andere Dateien enthält. Falls Ihr altes Projekt eine andere Verzeichnisstruktur nutzte, können Sie sich daran gewöhnen, drush und composer direkt aus diesem Verzeichnis auszuführen und nicht nur aus Ihrem Root-Verzeichnis.

In früheren Anleitungen wurde drupal-composer/drupal-project verwendet, das jetzt durch das offiziell unterstützte Template drupal/recommended-project ersetzt wurde.

2. Dateien in das neue Composer-Projekt kopieren

Hinweis: Die folgenden Schritte sind nur für Websites notwendig, die mit einer Drupal-Version vor 8.8.0 erstellt wurden.

Wenn Ihr Projekt vor Drupal 8.8.0 erstellt wurde, müssen Sie nun benutzerdefinierte Module, Themes und Libraries aus dem alten Projektverzeichnis in das neue Composer-Projekt kopieren. Stellen Sie sicher, dass die Dateien in den korrekten Verzeichnissen landen, da die alte Ordnerstruktur abweichen kann.

Die korrekten Pfade finden Sie im Abschnitt „installer-paths“ Ihrer composer.json:

"extra": {
    "composer-exit-on-patch-failure": ...
    "patchLevel": {
        ...
    },
    "installer-paths": {
        "web/core": ["type:drupal-core"],
        "web/libraries/{$name}": ["type:drupal-library"],
        "web/modules/contrib/{$name}": ["type:drupal-module"],
        "web/profiles/contrib/{$name}": ["type:drupal-profile"],
        "web/themes/contrib/{$name}": ["type:drupal-theme"],
        "drush/Commands/{$name}": ["type:drupal-drush"]
    },
    "drupal-scaffold": {
        ...
    }
}

Auf Ihrer alten Site befanden sich die Module wahrscheinlich in /var/www/sites/html/modules/. Auf der neuen Site müssen sie in den Verzeichnissen gemäß installer-paths liegen, z. B. /var/www/sites/new_html/web/modules/.

• Benutzerdefinierte Themes liegen in /var/www/sites/new_html/web/themes/custom/
• Benutzerdefinierte Module liegen in /var/www/sites/new_html/web/modules/custom/
• Libraries liegen in /var/www/sites/new_html/web/libraries/
• Ihre hochgeladenen Dateien und Bilder befinden sich in /var/www/sites/new_html/web/sites/default/files/

 

Stellen Sie sicher, dass der Webserver Schreibrechte für das Dateiverzeichnis hat, wie Sie es bei einer Neuinstallation von Drupal tun würden. Lesen Sie den Abschnitt Zugriffsrechte und Eigentümer, wenn Sie mehr zu Dateiberechtigungen wissen möchten.

Angenommen, der Benutzer des Webservers ist www-data und der FTP-Benutzer heißt vftp. Dann führen Sie etwa Folgendes in der Kommandozeile aus, um die Rechte zu setzen:

# Setzen der Gruppe des Dateien-Verzeichnisses auf den Webserver-Benutzer
sudo chown -R vftp:www-data /var/www/sites/new_html/web/sites/default/files

# Erlauben, dass die Gruppe des Webservers Ordner im Dateien-Verzeichnis lesen und bearbeiten darf
sudo find /var/www/sites/new_html/web/sites/default/files -type d -exec chmod u=rwx,g=rwx,o= '{}' \;

# Erlauben, dass die Gruppe des Webservers alle Dateien im Dateien-Verzeichnis bearbeiten darf
sudo find /var/www/sites/new_html/web/sites/default/files -type f -exec chmod u=rw,g=rw,o= '{}' \;

Ihr files-Verzeichnis enthält alle von Benutzern hochgeladenen Dateien sowie einige temporäre Ordner, wie komprimierte Stylesheets oder gecachte Twig-Templates.

Falls Sie diese temporären Ordner vom alten Projekt in das neue kopiert haben, löschen Sie diese manuell. Diese Ordner sind in der Regel php/, js/, styles/ und css/ im Verzeichnis /var/www/sites/new_html/web/sites/default/files. Diese Dateien werden normalerweise automatisch nach einem Cache-Reset (drush cr) und Seitenaufruf neu generiert, daher können Sie sie ohne Bedenken löschen. Stellen Sie aber sicher, dass Sie vorher ein Backup haben ;-).

3. settings.php ins neue Projekt übernehmen

Kopieren Sie die Datenbank-Verbindungsinformationen und weitere Einstellungen aus der alten settings.php in das neue Projekt. Dabei handelt es sich vor allem um die Arrays $databases['default']['default'], $settings['hash_salt'], $settings['trusted_host_patterns'] sowie eventuelle Benutzerdefinierte Einstellungen. Vergleichen Sie dazu einfach die beiden settings.php Dateien.

Vergewissern Sie sich, dass $config_directories['sync'] auf ein existierendes Verzeichnis zeigt, vermutlich außerhalb des webroots, wo composer.json liegt. Wenn Drupal anders installiert wurde, kann dieser Pfad auch auf eine Datei im Verzeichnis sites/default/files/ zeigen. Stellen Sie sicher, dass der angegebene Pfad existiert und für den Webserver-Benutzer beschreibbar ist.

Vergessen Sie außerdem nicht, Entwicklungs-Einstellungen wie settings.local.php und development.services.yml in das neue Projekt zu kopieren.

4. Zusätzliche Module in die neue Composer-Konfiguration aufnehmen

Sie müssen nun alle zusätzlichen Module in die neue composer.json im neuen webroot eintragen.

Sie können Module entweder manuell in composer.json hinzufügen oder mit composer require die aktuellsten Versionen aller Module auf Ihre Site holen.

4.1 Liste der Module Ihrer Website erhalten

Wenn Sie Composer bisher nicht zur Verwaltung Ihrer Website genutzt haben, enthält Ihre alte composer.json keinen Modul-Liste-Abschnitt unter „require“. Sie müssen daher alle hinzugefügten (nicht benutzerdefinierten) Module manuell erfassen.

Sie können dies tun, indem Sie die Verzeichnisse modules/contrib/ oder modules/ Ihrer alten Website auflisten. In composer.json fügen Sie zu jedem Modulnamen einfach „drupal/“ hinzu. Zum Beispiel wird modules/contrib/devel zu drupal/devel.

Entwicklungs-Pakete wie drupal/devel oder drupal/kint sollten in require-dev eingetragen sein, wo Sie bereits webflo/drupal-core-require-dev finden.

4.2 Module manuell in composer.json hinzufügen

Bearbeiten Sie composer.json im Stammverzeichnis des neuen Projekts (z.B. /var/www/sites/new_html) und kopieren Sie die Paketlisten aus den alten composer.json Abschnitten „require“ und „require-dev“ in das neue composer.json. Beim manuellen Vorgehen müssen Sie selbst auf korrekte Modulversionen achten.

4.3 Module mit composer require installieren

Statt Modulnamen und Versionen manuell in composer.json einzutragen können Sie auch composer require drupal/<modulname> für jedes benötigte Modul ausführen. Sie können mehrere Module gleichzeitig hinzufügen, z.B. composer require drupal/modul1 drupal/modul2 drupal/modul3. Um Module in require-dev aufzunehmen, verwenden Sie composer require --dev drupal/<modulname>.

4.4 Composer Installation abschließen

Führen Sie composer install im Projektverzeichnis (z.B. /var/www/sites/new_html/) aus. Dadurch werden alle zuvor in composer.json eingetragenen Module heruntergeladen. Bei Problemen löschen Sie composer.lock und das vendor-Verzeichnis und versuchen es erneut.

Sie müssen nicht alle Module manuell aktivieren, da Sie entweder Ihre alte Datenbank verwenden oder die Datenbank des alten Sites importieren werden.

5. Datenbank aktualisieren und Cache leeren

Führen Sie alle verfügbaren Datenbank-Updates mit drush updb durch.

Leeren Sie anschließend den Drupal-Cache mit drush cr im Projektverzeichnis (/var/www/sites/new_html).

Wenn bei drush updb die Fehlermeldung „Missing $settings['hash_salt'] in settings.php“ erscheint, siehe unten Abschnitt „Fehlerbehebung“. Wahrscheinlich haben Sie einige Werte aus der alten settings.php vergessen zu kopieren.

6. Webserver-Konfiguration anpassen

Passen Sie die Konfiguration Ihres Webservers an, damit sie auf den neuen Webroot zeigt, z.B. /var/www/sites/new_html/web/. Wenn Sie php-fpm verwenden, passen Sie auch die php-fpm-Konfiguration (z.B. /etc/php/7.2/fpm/pool.d/yoursite.conf) an. Starten Sie Webserver und php-fpm nach Änderungen neu.

7. Fehlerbehebung

7.1 Warnungen oder Fehler im Bericht

Überprüfen Sie die Berichte Ihrer Website auf Warnungen oder Fehler. Wenn Sie diese Anleitung befolgen, ohne Ihre alte Website vorab auf die neueste Drupal-Version zu bringen, werden Core und Module vermutlich auf neueste Versionen aktualisiert, was zu neuen Warnungen oder Fehlern führen kann. Beheben Sie diese wie bei einem normalen Drupal-Update.

7.2 Fehlender Hash Salt

Wenn Sie bei drush updb oder drush cr den Fehler „Missing $settings['hash_salt'] in settings.php“ erhalten, haben Sie wahrscheinlich vergessen, den Wert $settings['hash_salt'] aus der alten settings.php zu kopieren. Entweder kopieren Sie den hash_salt aus Ihrer alten settings.php oder generieren einen neuen Hash mit folgendem Befehl im Root-Verzeichnis Ihrer Site:

drush php-eval 'echo \Drupal\Component\Utility\Crypt::randomBytesBase64(55) . "\n"'

Dieser Befehl gibt einen neuen Hash aus, den Sie einfach in Ihre neue settings.php einfügen können.