Composer update sur Drupal : bonnes pratiques

Sur un site Drupal moderne, Composer n'est pas un détail technique : c'est le système nerveux de votre projet. Il gère le core, les modules contribués, les bibliothèques tierces et leurs dépendances mutuelles. Un composer update mal préparé peut casser une page, désactiver un formulaire ou provoquer une erreur fatale en production. À l'inverse, un composer update exécuté selon un workflow rigoureux est une opération routinière, prévisible et réversible.

La différence ne tient pas à la commande elle-même, qui est triviale, mais à ce qui l'entoure : la préparation, l'environnement de validation, les tests et le plan de retour arrière. Cet article décrit le workflow complet qu'une équipe sérieuse applique à chaque mise à jour, les commandes utiles, la mécanique de composer.json et composer.lock, la résolution des conflits de dépendances, les pièges courants et la stratégie de rollback.

Le workflow complet, étape par étape

Un composer update ne se lance jamais directement en production. Il suit un parcours balisé qui transforme une opération risquée en procédure maîtrisée.

Étape 1 : la sauvegarde. Avant toute chose, sauvegardez la base de données et les fichiers. Une mise à jour qui modifie le schéma de base ou la configuration n'est pas toujours réversible sans restauration. Avec Drush, l'export de la base est immédiat :

drush sql-dump --result-file=../backup-$(date +%Y%m%d-%H%M).sql --gzip

Sauvegardez aussi le dossier sites/default/files et, idéalement, l'export de configuration courant (drush config:export). Cette sauvegarde est votre filet de sécurité : sans elle, le rollback devient une reconstruction.

Étape 2 : reproduire l'état en staging. La mise à jour se valide d'abord sur un environnement de staging qui reflète la production : même version de PHP, même base de données (une copie récente), mêmes modules activés. Un environnement local reproductible, type DDEV ou Lando, facilite cette parité. Mettre à jour sur un staging qui diverge de la prod, c'est valider dans le vide.

Étape 3 : lancer la mise à jour. Sur staging, exécutez la mise à jour. Pour cibler proprement le core et les dépendances liées :

composer update drupal/core-* --with-all-dependencies

Pour mettre à jour un module précis plutôt que tout l'arbre :

composer update drupal/pathauto --with-dependencies

Le drapeau --with-dependencies (ou -w) autorise Composer à mettre à jour les dépendances directes du paquet ciblé. --with-all-dependencies (ou -W) étend cela à toute la chaîne. Un composer update sans argument met à jour l'ensemble des paquets dans les limites autorisées par composer.json : utile, mais à réserver aux mises à jour planifiées et bien encadrées.

Étape 4 : appliquer les mises à jour de base et vider les caches. Télécharger le nouveau code ne suffit pas. Drupal doit appliquer les hooks de mise à jour et reconstruire ses caches :

drush updatedb -y
drush cache:rebuild

drush updatedb (alias updb) exécute les mises à jour de schéma et de données livrées par le core et les modules. drush cache:rebuild (alias cr) reconstruit le cache, indispensable après tout changement de code. Si votre site utilise la gestion de configuration, vérifiez ensuite l'état avec drush config:status pour repérer toute divergence introduite par la mise à jour.

Étape 5 : tester. C'est l'étape qui sépare une mise à jour maîtrisée d'un pari. Vérifiez les pages critiques, les formulaires et l'authentification. Une suite de tests automatisés Drupal transforme cette validation de plusieurs heures de clics manuels en quelques minutes d'exécution, avec un verdict clair. Au minimum, lancez vos smoke tests sur les parcours principaux avant d'aller plus loin.

Étape 6 : déployer en production. Une fois la validation verte, le déploiement consiste à reporter en production exactement ce qui a été validé. C'est là qu'intervient composer.lock.

composer.lock contre composer.json : qui décide quoi

C'est la distinction la plus mal comprise et la source de la majorité des incidents évitables.

composer.json exprime vos intentions. Il déclare les contraintes de version : "drupal/core-recommended": "^11.0" signifie « accepte toute version 11.x supérieure ou égale à 11.0 ». C'est une fourchette, pas une version figée.

composer.lock enregistre la réalité. Il fige les versions exactes effectivement installées, avec leurs hashs. C'est ce fichier qui garantit que tous les environnements (local, staging, production) installent rigoureusement les mêmes versions.

La règle d'or en découle : composer update se lance en staging, jamais en production. En production, vous exécutez :

composer install --no-dev --optimize-autoloader

composer install lit le composer.lock et installe les versions exactes qui y sont figées. Le composer.lock validé en staging est commité dans Git, puis la production fait un composer install à partir de ce fichier. Vous déployez ainsi précisément ce que vous avez testé, sans surprise de résolution. Le drapeau --no-dev exclut les dépendances de développement (outils de test, debug) inutiles en production.

Résoudre les conflits de dépendances

Tôt ou tard, Composer affichera un message de conflit : un paquet exige une version qu'un autre interdit. C'est désagréable, mais c'est aussi Composer qui fait son travail en refusant d'installer une combinaison incohérente.

Diagnostiquer avant d'agir. La commande composer why-not explique pourquoi une version donnée ne peut pas être installée :

composer why-not drupal/core-recommended 11.1.0

À l'inverse, composer why drupal/token montre quels paquets dépendent d'un module donné, ce qui aide à comprendre pourquoi il reste bloqué sur une ancienne version. Ces deux commandes valent mieux que toute tentative à l'aveugle.

Les leviers de résolution. Selon le diagnostic, plusieurs pistes existent : mettre à jour le module qui impose la contrainte trop stricte, attendre une release compatible (fréquent juste après une version majeure du core) ou, en dernier recours, appliquer un patch via cweagans/composer-patches. Évitez autant que possible de relâcher des contraintes dans composer.json sans comprendre leur raison d'être : elles protègent souvent contre une incompatibilité réelle.

Le piège des plateformes. Beaucoup de conflits viennent d'un décalage de version PHP entre votre machine et le serveur. Déclarez la version cible explicitement pour que Composer résolve les dépendances comme en production :

composer config platform.php 8.3

Les pièges courants

Certaines erreurs reviennent régulièrement. Les connaître, c'est déjà les éviter.

Lancer composer update directement en production. C'est le scénario qui provoque le plus d'incidents. La résolution peut tirer des versions différentes de celles testées en staging, voire échouer à mi-chemin et laisser le site dans un état incohérent. En production, on installe, on ne met pas à jour.

Oublier drush updatedb ou drush cache:rebuild. Le code est à jour mais le schéma de base ou le cache ne l'est pas. Résultat : des erreurs intermittentes et difficiles à diagnostiquer. Ces deux commandes font partie intégrante de tout déploiement.

Tout mettre à jour d'un coup sans isoler les changements. Un composer update global qui touche des dizaines de paquets rend le débogage pénible si quelque chose casse. Procéder par lots (le core d'un côté, les modules de l'autre) garde des commits lisibles et un historique exploitable.

Ignorer les avis de sécurité. Drupal publie ses avis de sécurité les mercredis. La commande composer audit signale les dépendances vulnérables connues. L'intégrer à votre cycle évite de découvrir une faille trop tard.

Ne pas commiter le composer.lock. Sans lui versionné, chaque environnement résout les dépendances à sa façon et la parité disparaît. Le composer.lock doit toujours être dans Git.

Le rollback : prévu, pas improvisé

Même avec un workflow rigoureux, une régression peut atteindre la production. La différence entre un incident mineur et une crise tient à la préparation du retour arrière.

Le rollback du code. Comme composer.lock est versionné, revenir à l'état précédent consiste à restaurer la version antérieure du fichier, puis à réinstaller :

git checkout HEAD~1 -- composer.lock composer.json
composer install --no-dev --optimize-autoloader
drush cache:rebuild

Le rollback de la base. Si la mise à jour a exécuté des drush updatedb qui ont modifié le schéma, le retour du code seul ne suffit pas : il faut restaurer la sauvegarde de base prise à l'étape 1. C'est précisément pour ce moment que la sauvegarde existe.

drush sql-drop -y
gunzip < ../backup-20260811-1430.sql.gz | drush sql-cli
drush cache:rebuild

La règle de décision. Un rollback se décide vite et se documente. Notez ce qui a échoué, isolez le paquet en cause, puis reprenez le cycle de mise à jour avec le correctif. Un retour arrière n'est pas un échec : c'est le système de sécurité qui fonctionne.

L'industrialisation par la maintenance

Appliquer ce workflow une fois est faisable. L'appliquer chaque mois, sur chaque site, avec la même rigueur, demande de l'organisation. C'est exactement ce qu'apporte un cycle de maintenance Drupal structuré : des mises à jour planifiées, validées en staging, couvertes par des tests et accompagnées d'un plan de rollback documenté. La combinaison de Composer bien maîtrisé et de tests automatisés transforme les mises à jour d'une corvée anxiogène en routine sereine, ce qui maintient votre site sécuritaire et prêt pour la prochaine migration majeure.

Bien outillé, composer update cesse d'être un risque pour devenir un levier : vous restez à jour côté sécurité, vous capitalisez sur les améliorations du core et vous gardez la dette technique sous contrôle.

Vous voulez sécuriser vos mises à jour Drupal et mettre en place un workflow Composer fiable ? Parlons de votre projet et bâtissons ensemble un cycle de maintenance adapté à votre stack.