Ajouter Composer à un site existant

Simplifié dans Drupal 8.8.0

Remarque : si vous avez démarré votre projet avec Drupal version 8.8.0 ou supérieure, votre site utilise déjà la structure de fichiers correcte et est prêt pour la conversion vers Composer.

Cette page est un guide étape par étape pour ajouter manuellement le support Composer à un site existant, précédemment installé sans Composer. Ce guide s’adresse à ceux qui ont installé Drupal 8 manuellement depuis une archive ou utilisé un ancien template Composer, comme drupal/drupal.

Pour les sites créés avec Drupal 8.8.0 ou plus récent

Même si vous avez installé Drupal 8.8.0 depuis une archive, Composer est préinstallé. Vous devriez donc pouvoir gérer votre site avec Composer sans actions additionnelles de conversion.

Pour les sites créés avant Drupal 8.8.0

Le fichier composer.json fourni avec les archives téléchargées depuis https://www.drupal.org/download avant Drupal 8.8.0 n’était pas conçu pour un site géré par Composer.

Si vous souhaitez passer de la gestion manuelle à l’utilisation de Composer pour installer et mettre à jour le noyau Drupal et les modules supplémentaires, vous devez d’abord modifier le fichier composer.json de votre site.

Messages d’erreur typiques de Composer indiquant un mauvais fichier composer.json :

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.

Parfois, les problèmes liés aux templates Composer peuvent être résolus en supprimant le fichier de verrouillage composer.lock et le dossier vendors (composer.lock et vendor/) avant de relancer la mise à jour Composer, mais convertir un site Drupal 8 existant en projet géré via le template Composer recommandé dans le guide d’installation Drupal 8 (3.5. Utiliser Composer pour télécharger et mettre à jour les fichiers) reste une solution plus stable pour gérer les mises à jour Drupal.

Les outils gocomposer et composerize drupal tentent d’automatiser la conversion des anciens sites en projets Composer, mais la conversion manuelle est assez simple même pour des sites volumineux et ne prend pas beaucoup de temps.

À la fin, votre projet aura la structure de répertoire recommandée. La configuration Composer (composer.json, composer.lock, etc.), Drush et le dossier vendors seront situés hors de votre webroot. Votre ancien webroot contiendra un nouveau dossier nommé web/ où se trouve le vrai site web. Si votre projet utilise actuellement une autre organisation de dossiers, vous devrez mettre à jour la configuration de votre serveur web pour pointer vers ce nouveau dossier web/. Nous y reviendrons plus tard.

TL; DR ?

1. Installez un nouveau site Drupal avec le template Composer actuel dans un nouveau dossier.
2. Copiez tous les thèmes, modules, fichiers et configurations personnalisés dans le nouveau projet. (Vérifiez bien la structure des dossiers.)
3. Transférez les configurations dans le nouveau projet.
4. Ajoutez tous les modules ajoutés dans le nouveau composer.json et lancez l’installation via composer.
5. Mettez à jour la base de données et videz le cache (drush updb; drush cr).
6. Mettez à jour la configuration du serveur web.

 

HISTOIRE COMPLÈTE

Ces instructions supposent que votre site web actuel est dans /var/www/sites/html/ et que vous allez créer un nouveau site dans /var/www/sites/new_html/. Adaptez les chemins selon vos répertoires réels.

Avant de commencer

Si vous souhaitez « composer » votre ancien site Drupal, le noyau et les modules contrib utilisés ne seront probablement pas à leurs dernières versions. Si vous suivez ce guide à la lettre, le noyau Drupal et tous les modules seront mis à jour vers leurs dernières versions. C’est sans doute ce que vous voulez, mais pensez à la configuration de votre site. Y a-t-il de bonnes raisons de ne pas mettre à jour tous les modules ou le noyau vers leur dernière version ? Peut-être avez-vous une installation qui dépend d’une ancienne version d’une librairie ou d’un module contrib et ne doit pas être mise à jour.

Si vous souhaitez tout mettre à jour vers la dernière version, suivez ce guide et résolvez les problèmes qui surviennent après la mise à jour. Vous verrez probablement quelques erreurs ou avertissements liés aux nouvelles versions des modules. Cherchez simplement sur Internet ces messages pour trouver des correctifs.

Si vous préférez rester avec vos versions actuelles et mettre à jour plus tard avec Composer, vous devez vous assurer d’installer les mêmes versions des modules du noyau et contrib que celles utilisées sur votre ancien site. Consultez les guides composer create-project pour télécharger une version spécifique du noyau ou une version spécifique des modules contrib. Enfin, spécifiez ces versions avant d’exécuter composer create-project ou composer require. (Par exemple : composer require vendor/package:version)

1. Installez un nouveau site Drupal

Créez un nouveau projet Drupal à partir du template drupal/recommended-project :

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

Cela créera le dossier new_html/ dans le répertoire courant, contenant les dossiers vendors et web (= webroot), ainsi que composer.json, fichiers, etc. Si votre ancien projet n’utilisait pas cette structure, vous pourrez désormais exécuter drush et composer directement depuis ce dossier, pas seulement depuis la racine.

Ces instructions recommandaient auparavant d’utiliser drupal-composer/drupal-project, désormais déprécié au profit du template officiel : drupal/recommended-project

2. Copiez les fichiers dans le nouveau projet Composer

Note : Ces instructions concernent uniquement les sites créés avant Drupal 8.8.0.

Si votre projet a été créé avant Drupal 8.8.0, vous devez maintenant copier vos modules, thèmes et bibliothèques personnalisés de l’ancien dossier vers le nouveau projet. Assurez-vous de placer ces fichiers dans les bons dossiers du nouveau projet, car votre ancienne organisation peut différer.

Les chemins corrects se trouvent dans la section « installer-paths » de votre 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": {
        ...
    }
}

Sur votre ancien site, les modules étaient probablement dans /var/www/sites/html/modules/. Sur le nouveau, ils doivent être placés dans le dossier indiqué par installer-paths : /var/www/sites/new_html/web/modules/.

• Les thèmes personnalisés sont dans /var/www/sites/new_html/web/themes/custom/
• Les modules personnalisés sont dans /var/www/sites/new_html/web/modules/custom/
• Les bibliothèques sont dans /var/www/sites/new_html/web/libraries/
• Vos fichiers et images téléchargés sont dans /var/www/sites/new_html/web/sites/default/files/

 

Vérifiez que le serveur web a les permissions d’écriture sur le dossier files, comme lors de l’installation d’un nouveau site Drupal. Consultez la section Protéger les droits d’accès et la propriété des fichiers pour plus d’informations.

Supposons que l’utilisateur du serveur web soit www-data et l’utilisateur FTP vftp. Exécutez depuis la ligne de commande :

# Définir le groupe du dossier files à l’utilisateur du serveur web
sudo chown -R vftp:www-data /var/www/sites/new_html/web/sites/default/files

# Autoriser le groupe serveur web à modifier et accéder aux dossiers dans files
sudo find /var/www/sites/new_html/web/sites/default/files -type d -exec chmod u=rwx,g=rwx,o= '{}' \;

# Autoriser le groupe serveur web à modifier tous les fichiers dans files
sudo find /var/www/sites/new_html/web/sites/default/files -type f -exec chmod u=rw,g=rw,o= '{}' \;

Votre dossier files contient tous les fichiers téléchargés par les utilisateurs sur votre ancien site ainsi que certains dossiers de fichiers temporaires comme les feuilles de style compressées ou les templates de cache.

Si vous avez copié ces dossiers de fichiers temporaires de l’ancien site vers le nouveau dossier files, supprimez-les manuellement. Ces dossiers sont généralement php/, js/, styles/ et css/ dans /var/www/sites/new_html/web/sites/default/files. Ces fichiers sont automatiquement régénérés après un vidage de cache (drush cr) et la visite du site, vous pouvez donc les supprimer sans souci. Mais assurez-vous d’avoir une sauvegarde avant ;-).

3. Transférez settings.php dans le nouveau projet

Copiez les informations de connexion à la base de données, etc. depuis l’ancien settings.php vers le nouveau projet. Cela inclut les tableaux $databases['default']['default'], $settings['hash_salt'], $settings['trusted_host_patterns'], et éventuellement des configurations personnalisées. Comparez les deux fichiers settings.php pour voir ce qu’il faut copier.

Assurez-vous aussi que $config_directories['sync'] pointe vers un dossier existant, probablement hors du webroot où se trouve composer.json. Si vous avez installé Drupal autrement, il peut pointer vers un dossier dans sites/default/files/. Vérifiez que le chemin de $config_directories['sync'] existe et est accessible en écriture par l’utilisateur du serveur web.

N’oubliez pas de copier aussi les fichiers de configuration de développement settings.local.php et development.services.yml dans le nouveau projet.

4. Ajoutez les modules ajoutés dans la nouvelle configuration Composer

Vous devez maintenant ajouter tous les modules de votre projet dans le nouveau composer.json situé dans votre nouveau webroot.

Vous pouvez ajouter les modules manuellement dans composer.json ou utiliser composer require pour installer les dernières versions de tous vos modules.

4.1 Obtenir la liste des modules de votre site

Si vous n’utilisiez pas Composer pour gérer ce site, votre ancien composer.json ne liste pas les modules dans 'require'. Vous devrez donc collecter manuellement la liste des modules ajoutés (non personnalisés).

Pour ce faire, listez les dossiers dans modules/contrib/ ou modules/ selon votre organisation. Dans composer.json, ajoutez drupal/ devant chaque nom de dossier de module. Par exemple, modules/contrib/devel devient drupal/devel.

Placez les paquets de développement comme drupal/devel ou drupal/kint dans la section « require-dev », où vous trouverez déjà webflo/drupal-core-require-dev.

4.2 Ajouter les modules manuellement dans composer.json

Éditez composer.json à la racine du nouveau projet (par exemple /var/www/sites/new_html) et copiez la liste des paquets des anciennes sections « require » et « require-dev » dans le nouveau fichier. Avec cette méthode, vous devez gérer vous-même les versions des modules.

4.3 Installation des modules avec composer require

Au lieu d’ajouter manuellement les modules et versions dans composer.json, vous pouvez lancer composer require drupal/<nom_du_module> pour chaque module nécessaire. Vous pouvez ajouter tous vos modules en une seule commande : composer require drupal/module1 drupal/module2 drupal/module3. Utilisez composer require --dev drupal/<nom_du_module> pour ajouter un module dans require-dev.

4.4 Finaliser l’installation Composer

Lancez composer install depuis le dossier de votre projet (ex. /var/www/sites/new_html/). Cela téléchargera tous les modules ajoutés précédemment dans composer.json. En cas de problème, supprimez composer.lock et le dossier vendors, puis réessayez.

Vous n’avez pas besoin d’activer les modules manuellement, puisque vous utilisez soit la base de données de l’ancien site, soit vous importez la base de données de l’ancien site.

5. Mettez à jour la base de données et videz le cache

Appliquez toutes les mises à jour de la base de données disponibles en lançant drush updb.

Puis videz le cache Drupal avec drush cr depuis le dossier projet (/var/www/sites/new_html).

Si vous avez l’erreur Missing $settings['hash_salt'] in settings.php lors de drush updb, reportez-vous à la section « Dépannage » ci-dessous. Vous avez probablement oublié de copier cette valeur dans le nouveau settings.php.

6. Mettez à jour la configuration du serveur web

Modifiez la configuration de votre serveur web pour pointer vers le nouveau webroot, par exemple /var/www/sites/new_html/web/. Si vous utilisez php-fpm, mettez aussi à jour ses configurations (ex. /etc/php/7.2/fpm/pool.d/votresite.conf) pour pointer vers le nouveau webroot. N’oubliez pas de redémarrer les services après modification.

7. Dépannage

7.1 Avertissements ou erreurs dans le rapport d’état

Consultez les rapports de votre site pour vérifier l’absence d’avertissements ou d’erreurs. Si vous suivez ce guide sans avoir mis à jour votre ancien site à la dernière version avant, vous allez probablement mettre à jour le noyau et tous les modules à leur dernière version, ce qui peut générer des erreurs ou avertissements non présents avant. Corrigez-les comme après une mise à jour Drupal classique.

7.2 Hash Salt manquant

Si vous voyez l’erreur Missing $settings['hash_salt'] in settings.php lors de drush updb ou drush cr, vous avez probablement oublié de copier cette valeur depuis l’ancien settings.php. Copiez-la depuis l’ancien fichier ou générez-en une nouvelle avec cette commande à la racine de votre site :

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

Cette commande affiche une nouvelle valeur de hash que vous pouvez copier dans votre nouveau settings.php.