PHP 8 et Drupal : nettoyer vos dépréciations sans casser la prod

Pourquoi les messages de dépréciation masquent les vrais incidents

Un site Drupal actif en PHP 8.x peut générer plusieurs centaines de notices de dépréciation par requête. Sur une plateforme à trafic régulier, le volume atteint rapidement plusieurs milliers d'entrées par minute dans le watchdog ou dans les fichiers de log.

Résultat : les équipes de support et d'exploitation développent un réflexe de filtrage. On ignore les E_DEPRECATED, on règle les seuils de log à error uniquement, on ajoute une exclusion dans l'alerting. Et quand une vraie erreur fatale arrive — souvent liée à l'usage d'une API supprimée dans une mise à jour mineure — elle se noie dans le silence qu'on avait organisé.

La dépréciation n'est pas un signal de qualité cosmétique. C'est un signal de risque planifié : « cette API sera supprimée dans la prochaine version majeure ». L'ignorer, c'est programmer un incident futur avec une date d'expiration connue.

Activer la journalisation de façon contrôlée

Avant de corriger quoi que ce soit, il faut savoir exactement ce qui se déprécie — et dans quel contexte. L'enjeu n'est pas d'activer plus de logs, mais d'activer les bons logs au bon endroit.

Dans Drupal, les notices E_DEPRECATED et E_USER_DEPRECATED remontent par défaut dans la même table watchdog que les erreurs critiques. Pour les isoler sans polluer votre canal d'alerte principal, orientez uniquement les dépréciations vers un fichier ou un canal séparé via un handler PSR-3 comme drupal/monolog.

Pour une première cartographie sans exécuter le code, PHPStan avec le niveau de dépréciation activé donne un inventaire complet sur le code source :

vendor/bin/phpstan analyse web/modules/custom --level=5

Drupal Rector est l'outil de triage de référence : il connaît les règles de dépréciation du core depuis Drupal 8 et propose des correctifs automatiques. L'option --dry-run vous donne un aperçu complet sans toucher au code.

Trier ce qui est bloquant et ce qui peut attendre

Toutes les dépréciations ne se valent pas. On distingue trois niveaux :

• Critique : APIs déjà supprimées dans la version cible de votre prochain upgrade. Bloquantes, à corriger en priorité.
• Majeur : APIs encore disponibles mais dont le comportement changera. À planifier dans le prochain sprint.
• Mineur : modules contrib qui ont déjà publié leur version compatible. Souvent résolus par un composer update.

Générez un rapport JSON avec Rector pour disposer d'une source de vérité exploitable sprint après sprint :

vendor/bin/rector process web/modules/custom --dry-run --output-format=json > deprecations-report.json

Corriger progressivement, par lots livrables

Regroupez les corrections par périmètre métier, pas par type de dépréciation. Un lot qui touche plusieurs modules métier distincts est difficile à tester et à rollback. Un lot centré sur un seul périmètre est une PR propre, livrable et réversible.

Pour chaque lot, laissez Rector gérer les remplacements d'API mécaniques. Reviewez systématiquement les diffs avant de committer — les cas complexes (injections de dépendances refactorisées, hooks migrés en plugins PHP 8) nécessitent un ajustement manuel.

Fiabiliser la livraison avec des tests ciblés

Corriger une dépréciation sans test, c'est parier que le comportement fonctionnel n'a pas changé. Ce pari est généralement perdant sur des modules métier où la logique s'est accumulée sur plusieurs années.

Pour chaque lot, rédigez au minimum un test fonctionnel sur le parcours le plus critique du périmètre modifié. Quand une signature d'API a changé, ajoutez un test unitaire sur le service custom concerné.

Pour verrouiller l'entrée de nouvelle dette, intégrez une vérification PHPStan dans votre pipeline CI avec allow_failure: false. Quand un développeur introduit un appel d'API déprécié, la CI le signale avant la code review.

Ce que cette méthode change concrètement

Au bout de quelques sprints, cette méthode vous donne :

• Des logs qui signalent à nouveau les vrais incidents, parce que les dépréciations ne les noient plus.
• Un backlog de dette visible et priorisé, exploitable en planification.
• Des mises à jour Drupal prévisibles, parce que les blocages sont identifiés bien avant le jour J de l'upgrade.
• Une CI qui protège la qualité sans ralentir les livraisons.

L'objectif n'est pas zéro dépréciation immédiatement. C'est zéro surprise lors de votre prochain upgrade majeur.