Mise à jour du noyau via Composer
Cette documentation est incomplète. Ajoutez plus d’informations.
Des problèmes pour mettre à jour vers Drupal 8.8.0 ou une version ultérieure ?
Des changements majeurs ont été apportés dans Drupal 8.8.0 dans le cadre de l’initiative Composer, ce qui améliorera considérablement les workflows Composer pour la gestion des sites Drupal à long terme. Cependant, il existe certaines remarques particulières pouvant affecter la mise à jour depuis des versions antérieures.
Premiers pas
Pour comprendre comment Composer gère les dépendances de Drupal, consultez Utiliser Composer avec Drupal. Pour décider si Composer est une méthode raisonnable pour la mise à jour, comparez les options disponibles.
Pour plus de commodité, ces instructions incluent les commandes Drush nécessaires pour finaliser la mise à jour : beaucoup trouvent Drush plus rapide et plus simple que l’interface d’administration web.
Si ce site Drupal existe déjà et que Composer n’a jamais été utilisé auparavant, assurez-vous d’abord qu’il est prêt pour Composer.
Mise à jour du noyau Drupal 8
Premièrement, vérifiez que la mise à jour du noyau Drupal est réellement disponible :
composer update --dry-run "drupal/*"
Cela affichera toute mise à jour mineure ou patch disponible ; utilisez l’ancien format composer "drupal/*" si vous voulez savoir s’il existe des mises à jour pour les versions majeures. (Voir Semver 2.0 pour une explication des versions majeures, mineures et patch.) S’il n’y a pas de ligne commençant par drupal/core, Composer ne détecte aucune mise à jour. Notez s’il y a une ligne commençant par drupal/core-recommended. S’il y a une mise à jour, continuez avec les commandes ci-dessous.
Instruction de mise à jour en une étape
En supposant que vous soyez habitué à mettre à jour Drupal et que vous connaissiez toutes les précautions à prendre, la mise à jour est aussi simple que :
composer update drupal/core --with-dependencies drush updatedb drush cache:rebuild
Remplacez drupal/core par core-recommended si vous utilisez core-recommended sur votre site. Vous pouvez vérifier que votre site utilise core-recommended s’il est mentionné dans votre fichier composer.json, ou s’il est indiqué dans la sortie de composer update --dry-run quand vous vérifiez les mises à jour disponibles.
Si vous avez lancé votre site Drupal il y a un certain temps en utilisant drupal-composer/drupal-project, la commande ci-dessus peut ne pas fonctionner. Veuillez lire la liste ci-dessous.
Pour mettre à jour vers la version 8.8.0 ou ultérieure
La dernière version de drupal-composer/drupal-project est compatible avec Drupal 8.8.x. Cependant, si vous avez créé votre site avec ce projet il y a un certain temps (2019 ou avant), vous aurez probablement besoin d’effectuer quelques modifications ponctuelles lors de la première mise à jour vers la version 8.8.0 ou ultérieure. Ces modifications sont détaillées dans les remarques spéciales ci-dessous.
Si vous n’avez pas installé Drupal 8 avec Composer
Si vous n’avez pas installé Drupal 8 via Composer, vous devez convertir votre site en projet géré par Composer pour pouvoir mettre à jour Drupal avec les commandes ci-dessus. Voir Ajouter Composer à un site existant pour un guide étape par étape afin d’ajouter manuellement Composer à des sites Drupal 8 existants installés sans Composer.
Instructions détaillées de mise à jour
Toutes les étapes pour mettre à jour le noyau Drupal 8 avec Composer :
1. Faites toujours une sauvegarde de vos fichiers et de la base de données avant la mise à jour.
- drush sql:dump exportera la base de données
- Malheureusement, drush archive-dump a été supprimé dans Drush 9, vous devrez donc utiliser un outil CLI standard pour sauvegarder les répertoires nécessaires — généralement en excluant le répertoire vendor.
2. Lisez les notes de version principales. Certains modules ou thèmes ajoutés peuvent nécessiter une mise à jour pour fonctionner avec la nouvelle version mineure (par exemple 8.3–8.4) du noyau Drupal. Les releases de patch (par exemple de 8.4.4 à 8.4.5) ne devraient pas le demander. Pour détecter les modules ou thèmes nécessitant une mise à jour, lisez la page du projet ou les notes de version.
3. Activez le mode maintenance en activant l’état : définissez system.maintenance_mode 1, puis videz le cache : reconstruisez.
4. Si vous avez identifié certains modules ou thèmes nécessitant une mise à jour, suivez les instructions pour mettre à jour les modules.
5. Mettez à jour le noyau Drupal et toutes ses dépendances :
- Lancez la commande Composer suivante :
composer update drupal/core --with-dependencies
- Remplacez drupal/core ci-dessus par drupal/core-recommended si vous utilisez le template core-recommended.
- Si vous avez lancé votre site Drupal avec drupal-composer/drupal-project, consultez les remarques spéciales ci-dessous pour les étapes supplémentaires à effectuer lors de la première mise à jour vers 8.8.0 ou plus.
6. Appliquez ensuite toutes les mises à jour nécessaires de la base de données avec drush updatedb et videz le cache avec drush cache:rebuild.
7. Si vous utilisez la gestion de configuration pour déployer votre configuration, exportez la configuration avec drush config:export après la mise à jour de la base de données, car certaines mises à jour du noyau peuvent modifier la structure des fichiers de configuration ou introduire de nouvelles valeurs. Ajoutez l’option --diff pour voir les changements.
8. Vérifiez que votre site Drupal fonctionne correctement :
- Consultez la page de rapport d’état pour détecter les erreurs.
- Si le module journalisation base de données est activé, effectuez quelques opérations et vérifiez les journaux récents pour erreurs, avertissements, etc.
9. Désactivez le mode maintenance avec drush state:set system.maintenance_mode 0, puis videz le cache : drush cache:rebuild.
10. Après avoir désactivé le mode maintenance, vérifiez le site également en tant qu’utilisateur anonyme.
Dans votre environnement de production
- Il n’est pas nécessaire de répéter le reste du processus décrit ci-dessus, car composer install lira les pointeurs exacts de version pour tous les paquets depuis composer.lock, garantissant les mêmes versions dans les deux environnements.
- Si vous avez des serveurs de dev / staging et production séparés, assurez-vous de copier / fixer les fichiers composer.json et composer.lock en production et d’exécuter toujours composer install --no-dev en production, plutôt que composer update. L’option --no-dev empêchera l’installation de tout paquet listé dans 'require-dev', généralement des modules de débogage et des bibliothèques pour tests unitaires / fonctionnels.
Remarques spéciales sur la mise à jour vers Drupal 8.8.0 et plus
Le partenaire officiel du programme bêta Drupal PreviousNext a publié une entrée de blog utile sur les étapes qu’ils ont suivies pour passer de Drupal 8.7 à la bêta Drupal 8.8.0, ce qui peut aider d’autres propriétaires de sites rencontrant des problèmes avec cette mise à jour.
La principale cause de problèmes lors de la mise à jour des versions précédentes de Drupal vers Drupal 8.8.0 avec Composer est le passage de l’utilisation d’un template composer fourni par la communauté à un nouveau template officiel drupal/recommended-project. Les étapes suivantes de dépannage devraient corriger votre installation pour que vous puissiez utiliser les instructions de mise à jour standard, comme décrit ci-dessus.
Essayez de supprimer le répertoire /vendor
La suppression de votre répertoire vendor peut parfois résoudre des conflits lors de la mise à jour avec composer. Pour cela :
cd your_install_dir rm -rf vendor
Ensuite, vous pouvez continuer à exécuter ces actions de dépannage et/ou poursuivre la commande de mise à jour composer.
Migrer de webflo/drupal-core-strict vers drupal/core-recommended
Avant la version 8.8.0, beaucoup de sites utilisaient le métapaquet webflo/drupal-core-strict pour verrouiller les dépendances sur des versions exactes utilisées/testées avec le noyau Drupal (principalement des paquets Symfony). Depuis la version 8.8.0, le noyau Drupal fournit le paquet drupal/core-recommended pour réaliser cette fonction. Cependant, le passage de l’ancienne méthode à la nouvelle ne se fait pas automatiquement lors de la mise à jour vers le noyau 8.8.0, et le paquet webflo/drupal-core-strict ne fonctionne pas avec 8.8.0.
La méthode la plus simple pour effectuer cette migration et éviter les conflits est de supprimer complètement le fichier composer.lock comme partie de la mise à jour. Cependant, cela signifie que d’autres dépendances (par exemple des modules Drupal ajoutés) peuvent également être mises à jour. Suivez ces étapes pour garantir que seules les mises à jour désirées sont appliquées :
- composer update # Met à jour les dépendances en une étape séparée.
- git add composer.lock; git commit # Enregistrez les mises à jour dans un commit séparé.
- composer remove webflo/drupal-core-strict --no-update
- composer remove drupal/core --no-update
- composer require 'composer/installers:^1.7' --no-update
- rm composer.lock
- rm -rf vendor # Aide aussi à éviter les conflits.
- composer require drupal/core-recommended:^8.8 --update-with-dependencies
- git add composer.json composer.lock; git commit -m "Update Drupal to 8.8.0 and use drupal/core-recommended instead of webflo/drupal-core-strict"
Migrer de webflo/drupal-core-require-dev vers drupal/core-dev
Si vous avez créé votre site il y a un certain temps, il peut utiliser le métapaquet webflo/drupal-core-require-dev pour inclure les dépendances de développement Drupal nécessaires aux tests unitaires et fonctionnels. Si vous n’utilisez pas ces dépendances en développement, vous pouvez simplement supprimer webflo/drupal-core-require-dev. Sinon, vous devez commencer à utiliser le projet drupal/core-dev.
Premièrement, le paquet ancien d’outils de développement doit être supprimé :
composer remove --dev webflo/drupal-core-require-dev
Si vous n’avez pas besoin des outils de développement, vous pouvez vous arrêter ici. Si vous souhaitez les réinstaller via la méthode officielle, lancez :
composer require --dev drupal/core-dev
Mise à jour des patchs
Si vous appliquez des patchs en utilisant cweagans/composer-patches, ces patchs devront peut-être être remis à jour. Une fois le patch remis à jour, vous devrez modifier la section extra/patches de votre composer.json.
Mise à jour des dépendances souples en conflit
Parfois, une dépendance logicielle est installée dans une version incompatible avec la dernière version de Drupal. La solution consiste à composer require des versions spécifiques de ces modules qui mettent à jour le noyau, puis à supprimer les dépendances.
L’exemple suivant est tiré d’un excellent article de PreviousNext :
Premièrement, il faut le nouveau noyau et ses dépendances :
composer require --update-with-dependencies \ drupal/core:^8.8.0 \ symfony/finder:^3.4 \ symfony/filesystem:^3.4
Ensuite, il faut le nouveau paquet core-dev et ses dépendances :
composer require --dev --update-with-dependencies \ drupal/core-dev:^8.8.0 \ symfony/debug:^3.4
Enfin, supprimez les dépendances temporaires :
composer remove -n \ symfony/finder \ symfony/filesystem \
composer remove -n --dev symfony/debug
Mise à jour de la base de données de configuration et du schéma
Après avoir mis à jour le code, vous devrez peut-être mettre à jour la configuration et le schéma de la base de données :
drush updb drush cr drush config-export
Mise à jour de Settings.php
Dans Drupal 8.8.0, le répertoire de synchronisation est défini dans $settings, et non dans $config_directories, donc le fichier Settings.php doit être mis à jour.
Changez simplement de :
$config_directories['sync'] = 'foo/bar';
en :
$settings['config_sync_directory'] = 'foo/bar';
Problèmes connus et contournements
Si vous lancez la commande composer update ci-dessus mais que drupal/core ne se met pas à jour, il existe peut-être une autre dépendance qui bloque la mise à jour de Drupal. Vous pouvez vérifier les blocages de dépendances avec la commande composer prohibits. Par exemple, si vous essayez de passer de la version 8.4.5 à 8.5.0, lancez composer prohibits drupal/core:8.5.0, cela affichera la liste des dépendances qui bloquent la mise à jour. Mettez à jour ces dépendances en même temps que drupal/core, et cela devrait fonctionner (par exemple, composer update drupal/core "symfony/*" --with-dependencies).
Les problèmes de mise à jour avec Composer sont souvent liés à des templates composer laissés en place ou à une mauvaise configuration dans composer.json. Assurez-vous d’utiliser un template composer comme recommandé au chapitre 3.5 du Guide utilisateur Drupal 8 « Utiliser Composer pour télécharger et mettre à jour les fichiers ». Consultez Ajouter Composer à un site existant pour un guide étape par étape pour ajouter Composer manuellement à des sites Drupal 8 existants installés sans Composer.
En janvier 2020, le template Composer drupal-composer/drupal-project pour les projets Drupal n’est plus le template recommandé pour Drupal 8.8 et plus. Jusqu’à la mise à jour du chapitre 3.5 du Guide utilisateur Drupal 8, consultez le Guide communautaire pour démarrer un site avec les templates de projet Composer.
Quelques autres problèmes et billets de blog pertinents pour une aide supplémentaire :
- Mise à jour vers Drupal 8.4.0 et Drush 9 avec Composer - billet de blog de Benji Fisher (@benjifisher) chez Isovera sur les problèmes de mise à jour de 8.3 à 8.4.
- Mise à jour vers Drupal core 8.4, guide étape par étape - billet de blog PreviousNext sur les problèmes de mise à jour de 8.3 à 8.4.
- Mise à jour vers Drupal 8.5 avec composer - billet de blog d’Eirik Morland (eiriksm) sur certains problèmes de 8.4 à 8.5.
- Composer échoue à mettre à jour de 8.4.4 à 8.5.0-alpha1 - de nombreuses idées pour résoudre les problèmes de mise à jour Composer.
- Problèmes pour mettre à jour votre site Drupal 8 ? Ce billet de blog est pour vous - billet pour un nouveau plugin GoComposer qui automatise la mise à jour et transforme votre site en template recommandé.
En cas d’erreurs et d’avertissements en cours de mise à jour, il est conseillé de les lire attentivement et de chercher des solutions dans les queues de problèmes avant de continuer. En cas d’erreurs fatales, il est recommandé d’arrêter la mise à jour et de recommencer à zéro avec une sauvegarde, comme recommandé précédemment.