Préambule

Cet article présente le retour d'expérience de la montée de version de Drupal 8 à Drupal 9 de deux sites de taille modeste, créés aux débuts de Drupal 8, et n'ayant ensuite subis que des mises à jour de sécurité.

Présentation de la procédure

La communauté a mûri au niveau des migrations, et les procédures sont désormais assez bien documentées. La montée de Drupal 8 à Drupal 9 ne fait pas exception. À noter que cette procédure devrait être identique pour les versions suivantes de Drupal également.

Globalement, nous pouvons la résumer à :

• La mise à jour du code communautaire via le gestionnaire de dépendances composer  et mise à jour du code développé spécifiquement pour le projet (manuellement, via un éditeur de code, ou via des outils d'assistance fournis par la communauté)
• La mise à jour de la base de données (via l'outil drush et sa commande drush updatedb)
• Le vidage des caches (drush cache:rebuild, aliasé en drush cr)
• Si, comme nous, vous utilisez le système de gestion de configuration de Drupal 8 familièrement appelé CMI (pour Configuration Management Initiative), l'export de la configuration modifiée lors de la mise à jour de la base de données (drush configuration:export, aliasé en drush cex)

Et voilà, c'est fini, et pour des petits sites, la procédure ne devrait vous prendre que quelques heures.

Rentrons maintenant un peu plus en profondeur dans cette procédure (le diable est dans les détails).

Mise à jour via composer

La théorie

Normalement, la mise à jour du cœur via composer est très simple, sous réserve que vous ayez déjà les dernières mises à jour des modules en Drupal 8 (si ce n'est pas le cas, commencez par mettre à jour votre site en utilisant les dernières versions du cœur et des modules Drupal 8 !) et la documentation officielle recommande de faire les 2 étapes suivantes :

composer require 'drupal/core-recommended:^9' 'drupal/core-composer-scaffold:^9' --update-with-dependencies --no-update
composer update

Séparer les 2 étapes permet théoriquement d'éviter certains problèmes de dépendance mutuelle.

Au passage, vous constatez que Drupal fournit désormais un outil de scaffolding (génération des fichiers statiques fournis avec le cœur). Si vous utilisiez sur vos projets Drupal 8 l'outil fournit par le modèle drupal-composer, pensez bien à faire la modification dans votre composer.json et à adapter la configuration de ce nouvel outil, par exemple :

    "extra": {
        "drupal-scaffold": {
            "locations": {
                "web-root": "web/"
            },
            "file-mapping": {                                          
                "[web-root]/robots.txt": false
            }
        },

La pratique

Déjà, si comme nous, vous travaillez sur des projets Drupal 8 assez anciens, il est probable que certaines dépendances vous empêchaient de mettre à jour composer en version 2. Nous vous recommandons de nettoyer votre composer.json et de mettre à jour composer  dès à présent, vous allez ainsi gagner beaucoup de temps (et vous éviterez les messages intempestifs sur la consommation mémoire de l'outil), surtout si vous travaillez en contexte de conteneurs Docker :

composer self-update --2

Ensuite, pour notre part, nous avons souvent dû manuellement supprimer le cœur Drupal 8 de notre composer.json pour permettre la mise à jour sans problème de versions ou dépendances incompatibles.

Puisque vous allez passer en Drupal 9, pensez à explicitement mettre également drush à jour pour profiter de sa version 10 !

Et si mes modules communautaires n'ont pas de version Drupal 9 ?

C'est prévu par la communauté !

Si ces modules disposent d'un patch permettant la compatibilité avec Drupal 9, vous pouvez alors utiliser un dépôt composer spécifique vous permettant de récupérer les modules Drupal 8 sans conflit de dépendance avec la version du cœur et inclure le patch dans votre composer.json :

    "repositories": {
        {
            "type": "composer",
            "url": "https://packages.drupal.org/lenient"
        },
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        }
    },



    "extra": {
        "patches": {
            "drupal/mon_module": {                                                 
                "123456789 - D9 Compatibility patch for mon_module: "https://www.drupal.org/files/issues/mon_module-123456789"
            }
        }
    }

Le composer install ou update devrait alors fonctionner sans problème.

Et si le patch n'existe pas ? Créez-le et contribuez à la communauté ! La plupart du temps, il suffit simplement d'ajouter dans le .info.yml de votre module :

core_version_requirement: ^8 || ^9

Adaptation du code personnalisé

Déclaration de compatibilité

Cette modification va devoir être faite également dans votre code personnalisé : dans tous vos modules et thèmes développés spécifiquement pour le projet, vous allez devoir rendre le code compatible avec Drupal 9.

Sur des sites simples, il vous suffira de modifier vos .info.yml (pensez bien à modifier celui du thème également) pour ajouter la compatibilité Drupal 9.

Au passage, dans le thème, la clé "base theme" est désormais obligatoire, pensez à vérifier vos fichiers .info.yml :

base theme: stable

Fonctions d'API

Ensuite, quelques fonctions d'API ont changé entre Drupal 8 et Drupal 9. Si vous avez suivi les change records au fur et à mesure de leur publication, vous n'aurez rien à faire, mais si ce n'est pas le cas, on peut citer au moins les fonctions de manipulation de fichiers (file_prepare_directory(), file_unmanaged_copy(), …).

Un service très utilisé a également changé de nom, veillez donc à remplacer dans votre code tous les appels à entity.manager par entity_type.manager.

Entités personnalisées

De même, si vous déclariez des entités personnalisées, elles peuvent désormais toutes potentiellement comporter des révisions et vous devrez donc ajouter à leur configuration les annotations suivantes :

 *   revision_metadata_keys = {
 *     "revision_user" = "revision_user",
 *     "revision_created" = "revision_created",
 *     "revision_log_message" = "revision_log",
 *   },

C'est tout ce que nous avons dû faire sur nos sites (qui étaient relativement modestes, il est possible que vous ayez plus de modifications à apporter).

Outils utiles

Pour faciliter la recherche du code déprécié, les outils d'analyse statique (phpstan, psalm) peuvent aider.

Pour la montée de niveau elle-même (et notamment la compatibilité des modules communautaires), le module Upgrade Status existe. Il s'intègre d'ailleurs avec phpstan.

Il existe même un module pour automatiser le remplacement des fonctions dépréciées : Rector.

Problèmes potentiels

Si vous utilisiez déjà le stockage de la configuration en Drupal 8, selon la version du cœur (ou du patch utilisé pour stocker la configuration dans les profils), il est possible que l'indication du répertoire concerné ait changé, et il vous faudra potentiellement remplacer dans le settings.php :

$config_directories['sync']

par

$settings['config_sync_directory']

C'est le seul problème que nous avons rencontré. Dans tous les autres cas, les messages d'erreurs étaient souvent très explicites.

Conclusion

La montée de version de Drupal 8 à Drupal 9 est clairement beaucoup plus simple que sur les versions plus anciennes, et dans la majorité des cas ne devrait prendre que quelques heures ou jours.

La communauté a également beaucoup évolué sur le sujet et tout est aujourd'hui plutôt correctement documenté ou outillé, et normalement, ce fonctionnement devrait être conservé pour les versions futures de Drupal.

Si toutefois vous rencontrez des problèmes lors de votre montée de version, contactez-nous !