Skip to content
PrestaShop

Migrer ses modules vers la branche 9.x : bonnes pratiques et erreurs à éviter

19 octobre 2026
Alexandre
15 min. de lecture
Migrer ses modules vers la branche 9.x : bonnes pratiques et erreurs à éviter

Une migration modules Drupal 9.x échoue rarement à cause d’un seul correctif : elle se bloque surtout lorsque le code personnalisé, les modules contribués et les dépendances n’ont pas été préparés en amont. La voie la plus sûre consiste à rendre l’instance compatible avec la branche 9.x avant le changement majeur, puis à appliquer les mises à jour dans un environnement maîtrisé.

Cette démarche concerne aussi bien les équipes qui maintiennent quelques extensions maison que les agences responsables d’un catalogue important de modules contrib. Elle demande un inventaire fiable, des décisions explicites sur les extensions à conserver et des tests, mais elle évite de transformer l’upgrade en intervention d’urgence sur une boutique ou un site en production.

La migration modules Drupal 9.x en bref

Réponse directe : mettez d’abord votre site à jour vers la dernière version mineure compatible de sa branche source, auditez les dépréciations avec Upgrade Status, corrigez ou remplacez les modules incompatibles, sauvegardez code et données, puis exécutez la montée vers 9.x et ses mises à jour dans un environnement de test. Ne sautez jamais les mises à jour intermédiaires signalées par Drupal.

Drupal a conçu la transition de Drupal 8 vers Drupal 9 comme une succession de petites étapes plutôt que comme une refonte brutale. Ce principe est déterminant : Drupal 8.8 et 8.9 constituaient une base « Drupal 9-ready » lorsque leurs dernières versions mineures étaient appliquées. Le code, la base de données et les modules contribués pouvaient ainsi être assainis avant le passage à la nouvelle majeure.

Concrètement, migrer ne signifie pas seulement modifier la contrainte de version du cœur. Une extension peut rester installable tout en appelant une API supprimée, dépendre d’un projet contrib non compatible ou s’appuyer sur une partie interne du système. La réussite se mesure donc à la compatibilité réelle du comportement, des données et des dépendances, pas à la seule absence d’erreur au moment de l’installation.

  • La branche source doit être à son dernier niveau mineur compatible avant toute montée majeure.
  • Les appels à des API dépréciées doivent être corrigés avant Drupal 9, car les API dépréciées en Drupal 8 ont été retirées de Drupal 9.0.0.
  • Chaque module contrib doit avoir un statut de compatibilité vérifié, et non supposé.
  • Les extensions dépréciées, obsolètes ou inutiles doivent être traitées comme des décisions de maintenance à part entière.

Cette préparation progressive a un avantage opérationnel important : elle isole les causes. Si une régression apparaît durant l’audit de dépréciation, l’équipe sait qu’elle relève du correctif apporté. Si elle survient après une mise à jour du schéma, le périmètre d’investigation est plus court. À l’inverse, cumuler mise à jour du cœur, changement de modules et réécriture du code rend le diagnostic coûteux.

Construire l’inventaire avant de toucher à la branche source

La première étape utile n’est pas l’exécution d’une mise à jour : c’est l’établissement d’un inventaire exploitable. Listez le cœur installé, les modules contrib activés ou simplement présents, les modules maison, les thèmes et les bibliothèques dont vos extensions dépendent. Distinguez particulièrement ce qui est réellement activé de ce qui est conservé dans le dépôt sans être utilisé.

Pour une équipe e-commerce, cet inventaire doit aussi relier les extensions aux fonctions métier : tunnel de commande, catalogue, paiement, transport, compte client, exports, synchronisations, référencement, formulaires et traitements planifiés. Une extension peu visible dans l’administration peut être essentielle à un flux externe ; sa désinstallation ne doit donc jamais être décidée uniquement parce qu’elle paraît ancienne.

Classer les modules selon la décision à prendre

Un inventaire devient actionnable lorsqu’il ne se contente pas de nommer les projets. Pour chaque élément, attribuez une décision provisoire et un responsable. Les catégories suivantes évitent les zones grises :

  • Conserver et mettre à jour : le module est nécessaire et une version compatible existe.
  • Corriger : le module maison, ou un correctif maintenu localement, utilise des API dépréciées.
  • Remplacer : la fonction reste utile, mais le projet installé ne fournit pas de compatibilité adaptée.
  • Désinstaller : la fonction n’est plus nécessaire ou l’extension est devenue obsolète.
  • Investiguer : le rôle fonctionnel ou les dépendances ne sont pas encore établis.

Cette classification doit inclure les dépendances indirectes. La transition vers Drupal 9 ne concerne pas uniquement les API du cœur : des dépréciations peuvent aussi provenir de dépendances tierces telles que Twig et Symfony. Un module custom peut donc sembler propre du point de vue de ses appels Drupal tout en nécessitant une adaptation liée à une bibliothèque qu’il exploite.

Ajoutez enfin une colonne consacrée au risque de retour arrière. Si un module est remplacé, quelles données produit-il ou consomme-t-il ? Quelle configuration doit être migrée ? Quel service, gabarit Twig, formulaire ou intégration peut être touché ? Ces questions ne préjugent pas d’un problème, mais elles transforment une décision technique en plan de vérification concret.

Mettre à niveau la branche source avant l’upgrade vers Drupal 9

La montée vers la dernière version mineure compatible de la branche source est une condition de préparation, pas une formalité administrative. Drupal recommande de passer par les dernières versions mineures de Drupal 8.8 ou 8.9 avant Drupal 9 afin de disposer d’une base prête pour Drupal 9 concernant le code, la base de données et les projets contribués.

Cette séquence progressive permet d’exposer les dépréciations tant qu’un environnement compatible les signale encore. Elle réduit aussi le risque de rencontrer simultanément une incompatibilité de module, une évolution de schéma et un changement de dépendance. Le bénéfice n’est pas de supprimer tous les tests : c’est de rendre chaque test interprétable.

  1. Créez un environnement de travail représentatif de la production, avec une copie appropriée du code, de la configuration, des fichiers et de la base de données.
  2. Appliquez les mises à jour nécessaires sur la branche source jusqu’à sa dernière version mineure compatible.
  3. Exécutez les mises à jour prévues, puis vérifiez l’état applicatif avant de préparer Drupal 9.
  4. Auditez les modules et le code custom, corrigez les dépréciations prioritaires et répétez les contrôles.
  5. Seulement après cette préparation, planifiez le changement vers la branche 9.x.

Ne confondez pas progression et lenteur. Une migration menée en phases peut avancer rapidement si les critères de sortie sont simples : aucune incompatibilité critique non traitée, modules indispensables identifiés, sauvegarde vérifiée et parcours métier validés. Le « saut » brutal paraît parfois plus court dans un planning, mais il reporte les décisions difficiles au moment où il est le plus risqué de les prendre.

Il faut aussi éviter d’attendre qu’une branche soit en fin de support pour agir. Drupal rappelle, par exemple, que des branches plus anciennes telles que 9.3.x ne bénéficient plus de support de sécurité. Une stratégie de compatibilité continue donne aux équipes le temps de corriger, de remplacer et de tester sans dépendre d’une fenêtre d’intervention contrainte.

Auditer les API dépréciées avec Upgrade Status

Upgrade Status est l’outil recommandé par Drupal.org pour identifier les problèmes de compatibilité dans les projets contribués et le code personnalisé avant une montée de version majeure. Son rôle est d’orienter l’effort : il aide à repérer les éléments qui demandent une correction ou une décision, au lieu de compter sur une lecture manuelle de tout le dépôt.

Le point à retenir est sans ambiguïté : toute API marquée dépréciée dans Drupal 8 a été retirée de Drupal 9.0.0. Un avertissement de dépréciation n’est donc pas une dette que l’on peut laisser indéfiniment dans un module destiné à fonctionner en 9.x. Il annonce un appel qui ne sera plus disponible après la migration.

Traiter les résultats dans le bon ordre

Commencez par les modules maison et les surcharges locales. Vous les maîtrisez, pouvez les corriger et avez la responsabilité de leur maintenance. Recherchez ensuite, pour les modules contrib, une version déclarée compatible ou un projet de remplacement adapté. Si une fonctionnalité du cœur supprimée est concernée, ne migrez pas en présumant que son comportement existe encore : Drupal recommande d’employer les projets de remplacement fournis ou des contribs adaptés lorsque cela est nécessaire.

Une fois une correction appliquée, contrôlez son effet fonctionnel. Remplacer une API ne consiste pas seulement à faire disparaître un message : le module doit continuer à respecter son contrat métier. Vérifiez notamment les permissions, les formulaires, le rendu, les traitements en arrière-plan, les intégrations externes et les données enregistrées par l’extension.

  • Associez chaque signal à un fichier, une extension, une dépendance et une personne responsable.
  • Notez le remplacement retenu et la raison du choix, surtout lorsqu’un module contrib est substitué.
  • Testez le comportement après la correction, pas uniquement l’absence de dépréciation détectée.
  • Conservez les résultats d’audit à chaque jalon afin de voir ce qui est résolu et ce qui reste bloquant.

Upgrade Status ne remplace toutefois ni la compréhension du code ni les tests métier. Il donne une visibilité précieuse sur la compatibilité technique ; il ne peut pas décider à votre place si un remplacement conserve exactement vos règles de catalogue, vos données clients ou vos processus internes. C’est pourquoi l’audit doit être relié à l’inventaire fonctionnel établi au départ.

Choisir entre mise à jour, remplacement et désinstallation des extensions

Un module contrib n’est pas automatiquement prêt pour Drupal 9 parce que beaucoup de projets l’étaient déjà. Drupal.org précise que beaucoup de modules contribués étaient compatibles, mais pas tous. La vérification préalable est indispensable, en particulier lorsque le module est central dans l’architecture ou lorsqu’il entraîne d’autres dépendances.

Vérifiez d’abord si une version compatible du projet répond au besoin sans rupture fonctionnelle. Si ce n’est pas le cas, étudiez un remplacement maintenu ou une adaptation du code maison. Le meilleur choix n’est pas toujours celui qui demande le moins de modifications immédiates : une dépendance fragile peut recréer la même urgence à la migration majeure suivante.

Lire correctement les statuts deprecated et obsolete

Depuis Drupal 9.3.0, une extension peut déclarer dans son fichier d’information un statut deprecated ou obsolete. Ces statuts ne doivent pas être ignorés sous prétexte que l’extension fonctionne encore aujourd’hui. Ils constituent des signaux d’alerte : préparez son remplacement ou sa désinstallation, et examinez les conséquences sur la configuration et les données.

Une extension dépréciée peut être retirée dans une version majeure suivante. Drupal prévoit alors une procédure de désinstallation et de mise à jour dédiée afin d’éviter les effets de bord. Retirer des fichiers du code sans désinstaller proprement l’extension n’est pas une alternative sûre : la base de données et la configuration peuvent encore référencer ce qui a été supprimé.

Conservez une extension parce qu’elle répond à un besoin vérifié et qu’un plan de compatibilité existe, non parce qu’elle est déjà présente dans le dépôt.

Dans certains cas, désinstaller est préférable à migrer. C’est le cas d’une fonction abandonnée, d’un module doublon ou d’une extension qui ne porte plus de valeur métier. Cette décision reste à encadrer : archivez les éléments utiles, identifiez les dépendances, validez les parcours affectés, puis suivez la procédure de désinstallation et de mise à jour prévue.

Corriger durablement les modules personnalisés pour Drupal 9.x

Les modules maison sont souvent l’endroit où se concentre le risque réel. Ils portent des règles propres à l’organisation et peuvent avoir été modifiés au fil des versions par plusieurs intervenants. L’objectif n’est pas uniquement de les faire passer en Drupal 9.x : il faut aussi les rendre plus simples à faire évoluer lors de la prochaine transition.

La politique de compatibilité de Drupal distingue les API stables des API internes. Les développeurs de modules ne doivent pas s’appuyer sur les parties internes ou non garanties. Une API interne peut convenir aux besoins du cœur sans constituer un contrat pour une extension ; bâtir un module sur elle expose donc à des ruptures sans garantie de compatibilité.

Transformer les dépréciations en contrat de migration

Lorsqu’une API publique de votre module doit évoluer, suivez les pratiques de dépréciation attendues par Drupal. La méthode ou le service appelé précédemment doit être clairement signalé avec @deprecated. Au moment de l’exécution, un @trigger_error(..., E_USER_DEPRECATED) rend l’usage encore existant visible. Le message doit renvoyer vers le change record approprié.

Cette discipline n’est pas réservée aux gros projets. Elle permet à une équipe, à une agence partenaire ou à un futur mainteneur de savoir qu’un appel fonctionne encore temporairement, pourquoi il doit changer et vers quoi le migrer. Elle applique le principe de compatibilité continue : les nouvelles API remplacent les anciennes par dépréciation, plutôt que par une suppression immédiate.

  • Exposez une API stable lorsque votre module est destiné à être étendu par d’autres composants.
  • Documentez toute modification d’API publique dans un change record ou des notes de version.
  • Fournissez une voie de remplacement explicite pour les appels dépréciés.
  • Évitez d’utiliser des éléments internes comme solution de contournement rapide.
  • Prévoyez la suppression d’une extension ou d’une API dépréciée dans une version majeure ultérieure, avec les mises à jour nécessaires, notamment hook_update_last_removed lorsque cela s’applique.

Documenter les changements publics réduit les ruptures invisibles. Un développeur qui met à jour un module dépendant peut consulter la modification annoncée, comprendre la nouvelle voie et planifier son adaptation. Sans cette information, les équipes découvrent le changement au moment d’un incident ou d’une montée de version, c’est-à-dire trop tard pour choisir sereinement.

Sauvegarder et tester la migration sans mettre la production en danger

Avant toute opération, sauvegardez le code et la base de données. La documentation d’upgrade rappelle également de sauvegarder le répertoire sites, les modules ajoutés et les fichiers téléversés. Ces éléments forment un tout : restaurer la base sans les fichiers associés, ou restaurer le code sans la configuration et les données correspondantes, ne garantit pas un retour à un état cohérent.

Une sauvegarde utile est une sauvegarde dont la restauration a été envisagée dans le scénario de travail. Définissez où se trouvent les copies, quelle version du code leur correspond et quel membre de l’équipe peut exécuter le retour arrière. Cette préparation protège autant contre une erreur humaine que contre une incompatibilité découverte après une mise à jour.

Valider des parcours, pas seulement des pages

Après chaque étape significative, testez les parcours liés aux modules migrés. Pour un site éditorial, cela peut couvrir la création, l’édition et l’affichage du contenu. Pour un site de vente, ajoutez les actions déterminantes de votre activité : navigation dans le catalogue, panier, commande, compte client, échanges avec les services tiers et traitements automatisés que vous exploitez.

  1. Vérifiez que les extensions attendues sont bien actives et que leur configuration est disponible.
  2. Exercez les fonctions front-office et back-office qui dépendent des modules modifiés.
  3. Contrôlez les données créées ou modifiées durant les tests, y compris les cas de mise à jour.
  4. Examinez les erreurs et avertissements apparus pendant les actions.
  5. Faites valider les parcours à fort enjeu par les personnes qui les utilisent réellement.

Un environnement de test réduit le risque, mais il ne dispense pas d’une fenêtre de déploiement préparée. Prévoyez les responsabilités, les contrôles post-déploiement et la décision de retour arrière. La migration technique et la vérification opérationnelle doivent suivre la même séquence, afin de ne pas déclarer une mise à niveau terminée avant d’avoir constaté que le service attendu est rendu.

Résoudre les erreurs de schéma et les mises à jour intermédiaires manquées

Le message « Unsupported schema version » mérite un arrêt et une analyse, pas un contournement. Il indique que Drupal détecte qu’une mise à jour intermédiaire a été sautée. La procédure recommandée consiste à revenir à la version du module qui contient les mises à jour manquantes, puis à relancer correctement les mises à jour.

Le réflexe consistant à modifier directement un numéro de schéma ou à poursuivre malgré l’avertissement peut donner l’impression de débloquer l’opération. Il fait cependant perdre la séquence de transformations prévue par le module. Or ces mises à jour peuvent être nécessaires pour aligner structure, données et configuration avec la version de code installée.

Une méthode de diagnostic sobre

  • Identifiez le module concerné et la version dont provient l’écart signalé.
  • Reconstituez la version qui contient les updates manquants.
  • Revenez à cette version dans l’environnement de travail, puis exécutez les mises à jour prévues.
  • Vérifiez le résultat avant de reprendre la progression vers la version cible.
  • Documentez l’incident et la séquence retenue pour éviter qu’elle soit à nouveau sautée.

Cette méthode peut sembler plus rigoureuse qu’un correctif direct, mais elle respecte le chemin de mise à niveau conçu par l’extension. Elle est particulièrement importante lorsque plusieurs modules partagent des données ou lorsqu’un site a connu des mises à jour anciennes et incomplètement documentées.

La leçon dépasse ce seul message : les updates doivent être considérées comme une suite ordonnée. Intégrez leur exécution et leur contrôle à chaque jalon de la migration modules Drupal 9.x. Vous réduirez les anomalies qui n’apparaissent qu’après coup, par exemple lors de l’édition d’un contenu ou de l’exécution d’un traitement dépendant d’une configuration ancienne.

Mettre en place une compatibilité continue après le passage en 9.x

Une migration vers Drupal 9 ne doit pas clore le travail de maintenance. La politique d’upgrade continu de Drupal repose sur le remplacement progressif des anciennes API par de nouvelles API via la dépréciation. Adopter cette logique au quotidien évite de recréer, à chaque grande version, un volume de corrections accumulées pendant des années.

Intégrez l’examen des dépréciations et des changements publics dans vos cycles habituels de mise à jour. Lorsqu’un module contrib évolue, vérifiez ses notes de version et son statut de compatibilité. Lorsqu’un module maison évolue, documentez les changements qui concernent ses utilisateurs techniques. Lorsqu’une extension devient inutile, planifiez sa désinstallation propre avant qu’elle ne devienne un obstacle.

Une routine légère suffit souvent à maintenir la visibilité : inventaire actualisé, audit avant les évolutions importantes, revue des dépendances Twig ou Symfony lorsqu’elles sont concernées, et tests ciblés sur les parcours métier sensibles. Cette organisation ne promet pas qu’aucune incompatibilité ne surviendra ; elle évite surtout qu’elle reste cachée jusqu’à une migration imposée.

Pour les propriétaires de sites, le résultat attendu est une plateforme plus prévisible. Pour les développeurs et agences, c’est un code dont les contrats sont lisibles, des remplacements anticipés et des interventions mieux estimables. La valeur de la préparation se trouve autant dans cette capacité à décider tôt que dans le passage effectif vers une branche 9.x.

Retenez l’ordre de priorité : mettre à jour la branche source, sauvegarder, auditer avec Upgrade Status, corriger les API dépréciées, vérifier chaque module contrib et traiter proprement les extensions obsolètes. En respectant les mises à jour intermédiaires et en testant les parcours réels, la migration devient une évolution contrôlée plutôt qu’un pari sur la production.

Partager cet article