Comment mettre à niveau vers Drupal 10 à partir de Drupal 8 ou 9 ? Guide complet

Les changements dans le monde numérique sont inévitables et nécessaires. Pour les utilisateurs et développeurs de Drupal, l'un des moments clés est la migration du système vers sa dernière version. Dans cet article de blog, je me concentre spécifiquement sur le processus de mise à niveau vers Drupal 10, vous guidant pas à pas à travers la préparation, les vérifications à effectuer et les actions à entreprendre pour que la transition soit la plus fluide possible.

Pourquoi Drupal 10 ?

La nouvelle version de Drupal a été officiellement lancée le 14 décembre 2022, marquant une étape essentielle dans le développement continu de ce système de gestion de contenu.

Passer à Drupal 10 est une question d'accès à de nouvelles fonctionnalités et améliorations, et c'est aussi un aspect important de la sécurité et de la stabilité de votre site web. Le support pour Drupal 9 a pris fin le 1er novembre 2023, rendant une mise à niveau non seulement recommandée mais, dans certains cas, nécessaire.

Différences entre Drupal 9 et Drupal 10

Drupal 10 apporte plusieurs améliorations visant à faciliter le travail et à améliorer la sécurité. Cependant, il n'introduit pas un changement complet dans la structure du système pour que la transition depuis les versions précédentes ne force pas l'utilisateur à s'adapter à un tout nouvel environnement.

Voici quelques changements fondamentaux par rapport à la version précédente du système :

• Olivero - nouveau thème frontend par défaut : Olivero remplace Bartik en tant que thème frontend principal, introduisant un design frais et moderne.
• Claro - nouveau thème administratif par défaut : Claro remplace Seven, offrant une interface administrative plus transparente conçue pour l'efficacité et la facilité d'utilisation.
• Remplacement partiel de jQuery par JavaScript : ce changement reflète une tendance dans le développement web, où JavaScript remplace progressivement jQuery en raison de ses performances et de sa flexibilité.
• Mise à jour de CKEditor à la version 5 : La dernière version de CKEditor a été entièrement réécrite. Elle offre de grandes possibilités d'expansion et d'intégration avec les technologies modernes.
• Suppression du support pour PHP en dessous de la version 8.1 : Drupal 10 nécessite PHP version 8.1 ou supérieure.
• Symfony version 6.2 : Contrairement à son prédécesseur, qui supportait ce framework dès la version 4, la dernière version de Drupal nécessite Symfony version 6.2. C'est un pas important dans l'amélioration de la sécurité et de l'optimisation des sites web basés sur ce système de gestion de contenu.

Modules et thèmes supprimés

Un autre changement significatif dans la dernière version de Drupal est la suppression de certains thèmes et modules qui avaient déjà le statut "obsolète" dans Drupal 9. Ils sont encore disponibles comme modules contribuant mais sont développés séparément et ne font pas partie du noyau de Drupal. Voici la liste :

Versions requises pour PHP et bases de données

Drupal 10 a des exigences système spécifiques que vous devez respecter pour assurer le bon fonctionnement de la plateforme. En plus de la version PHP 8.1 ou supérieure (8.1.6 est recommandée comme minimum), vous devez également vous assurer d'avoir la bonne version de base de données. Je présente une liste des versions compatibles ci-dessous :

Microsoft SQL Server et MongoDB sont également pris en charge via des modules contribuant séparés.

Préparation pour une mise à niveau de Drupal

Je recommande de créer une sauvegarde du site web et de la base de données avant de procéder à la mise à niveau. Cela vous permettra de restaurer rapidement votre page web en cas de problèmes. Assurez-vous également que votre hébergement prend en charge les versions PHP et de base de données requises par Drupal 10, comme je l'ai mentionné ci-dessus.

Migration depuis Drupal 8

En novembre 2021, le support pour Drupal 8 a pris fin, entraînant l'absence de nouvelles mises à jour de sécurité et de support technique pour cette version. Il vaut donc la peine de penser à migrer vers un système plus récent.

Pour les utilisateurs de Drupal 8 prévoyant de migrer vers Drupal 10, une mise à niveau initiale vers la version 9 est nécessaire. C'est une étape essentielle du processus de migration, permettant une adaptation harmonieuse aux derniers standards et fonctionnalités offerts par "dix". Une fois cette première phase de mise à niveau terminée, vous pouvez passer aux étapes suivantes. Pour plus d'informations et de conseils sur la mise à jour de votre système de Drupal 8 à 9, consultez notre article sur comment bien prendre soin d'une mise à jour de Drupal.

Migration de Drupal 9 à 10

Si vous passez de Drupal 9 à 10, vous devez être prêt à ce que le processus complet comporte plusieurs étapes. Je décris chacune d'elles ci-dessous pour vous faciliter la migration par vous-même.

1. Mise à jour de PHP vers la version 8.1

Si vous n'avez pas encore cette version ou une version supérieure, vous devez procéder à la mise à jour. Avant de commencer, vérifiez que tous les modules et thèmes de votre site web sont compatibles avec la version PHP plus récente. Des outils utiles pour ce processus sont PHP Codesniffer et PHP Compatibility.

2. Mise à niveau de Drupal 9 vers la dernière version

L'étape suivante consiste à mettre à niveau Drupal 9 vers une version minimale 9.4.4 (cependant, la dernière version, 9.5.11, est recommandée). Pour ce faire, vous pouvez utiliser les commandes suivantes :

composer update "drupal/core-*" --with-all-dependencies
drush cr -y
updb
drush cex -y

3. Désinstallation des thèmes avec le statut "obsolète"

Les thèmes Classy, Bartik, Stable, et Seven ont été supprimés dans la dernière version de Drupal. Donc, avant la mise à niveau, désinstallez-les de /admin/appearance. Cependant, si vous avez des thèmes basés sur ceux-ci, vous pouvez installer leurs versions contribuant en utilisant les commandes suivantes :

composer require drupal/seven 
composer require drupal/classy 
composer require drupal/bartik
composer require drupal/stable

4. Migration vers CKEditor 5

La migration de l'éditeur vers CKEditor 5 est un processus qui peut être plus compliqué qu'une mise à niveau standard, principalement parce que CKEditor 5 a été écrit à partir de zéro. La nouvelle architecture apporte de nombreuses fonctionnalités avancées et améliorations. Cependant, en raison d'une réécriture complète du code, tous les plugins disponibles dans CKEditor 4 ne seront pas directement compatibles avec la nouvelle version.

Avant la migration, il est important de vérifier soigneusement la compatibilité et la disponibilité des plugins que vous utilisez et éventuellement de les réécrire pour la dernière version de l'éditeur. Vous pouvez en savoir plus à ce sujet dans la documentation CKEditor.

Si tous les plugins sont compatibles, vous pouvez procéder aux étapes suivantes :

• Premièrement, allez à /admin/modules et installez le module CKEditor 5.
• Puis allez à /admin/config/content/formats et cliquez sur le bouton "Configurer" à côté de chaque format pour lequel vous souhaitez changer l'éditeur.

• Changez l'éditeur dans la zone marquée d'une flèche rouge ci-dessous et cliquez sur "Enregistrer" en bas de la page. Procédez de cette manière pour chaque format qui nécessite un changement.

• Dans la dernière étape, allez à /admin/modules/uninstall et supprimez le module CKEditor.

5. Mise à jour des modules utilisant Drupal Upgrade Status

Avant de commencer la mise à niveau, il est également recommandé d'installer le module Drupal Upgrade Status. La tâche principale de cet outil est d'analyser la compatibilité des modules et thèmes actuellement installés avec les standards de la nouvelle version système. Cela permet aux utilisateurs d'identifier rapidement les éléments qui doivent être mis à jour ou modifiés avant d'effectuer le processus de migration.

La première étape consiste à installer et activer le module :

composer require drupal/upgrade_status 
drush en upgrade_status 

Puis allez à /admin/reports/upgrade-status, sélectionnez les modules à vérifier, et cliquez sur le bouton "Analyser la sélection".

Après la fin du processus de balayage, vous recevrez un retour avec une liste de modules incompatibles avec Drupal 10.

Dans mon cas, il y a un problème avec le module Custom. Comme vous pouvez le voir dans l'image ci-dessous, le module Drupal Upgrade Status lui-même suggère une solution au problème. Dans ce cas, c'est une erreur liée à la version du noyau dans le fichier info.yml. J'ai corrigé les erreurs dans le code et l'ai scanné à nouveau - je vous recommande de faire de même.

Résolvez les problèmes de compatibilité jusqu'à ce que la barre dans le coin supérieur droit indique 100%.

Pour vos modules personnalisés, vous pouvez facilement effectuer vous-même les modifications nécessaires dans le code. Le plus souvent, les modules contribuent ont besoin d'être mis à jour vers les dernières versions prenant en charge Drupal 10.

Les choses se compliquent lorsque le module que vous utilisez ne prend pas encore en charge Drupal 10. Il existe plusieurs solutions à ce problème. L'une d'elles est un plugin pour Composer qui vous permet d'installer des modules qui ne sont pas encore compatibles avec Drupal 10. Ci-dessous, je vous suggère comment le faire.

La première étape consiste à installer le plugin :

composer require mglaman/composer-drupal-lenient

Ensuite, ajoutez le module que vous souhaitez mettre à jour en utilisant la commande :

composer config --merge --json extra.drupal-lenient.allowed-list '[module name]'

L'étape finale consiste à créer un patch pour ajouter la compatibilité de votre module avec D10 et le télécharger sur composer.json.

Si vous avez réussi à passer tout le processus, vous pouvez passer à l'étape suivante de la mise à niveau.

6. Mise à niveau du noyau Drupal vers la version 10

Avant de mettre à niveau le noyau Drupal, il est conseillé d'examiner composer.json et de supprimer les correctifs obsolètes qui sont incompatibles avec la nouvelle version. Après avoir terminé ce processus, implémentez les étapes suivantes.

Tapez la commande dans le terminal :

composer require 'drupal/core-recommended:^10' 'drupal/core-composer-scaffold:^10' 'drupal/core-project-message:^10' --update-with-dependencies --no-update

Si vous utilisez core-dev, utilisez celui-ci :

composer require 'drupal/core-dev:^10' --dev --update-with-dependencies --no-update

Puis augmentez Drush dans composer.json à la dernière version :

composer require 'drush/drush:^12' --no-update

Exécutez la commande :

composer update

Si les versions dans Composer fonctionnent sans erreur, exécutez :

drush cr -y
updb
drush cex -y

7. Tests du site web

Après la mise à niveau vers Drupal 10, il est important de réaliser des tests approfondis du site web dans un environnement local. Assurez-vous que toutes les fonctionnalités et éléments clés du site web fonctionnent correctement. Vous devriez vérifier des fonctions essentielles telles que les formulaires, la navigation, les performances des modules ou l'intégration avec des services externes. Il est également judicieux de revoir le site web de manière approfondie d'un point de vue visuel et d'examiner les journaux pour détecter d'éventuelles erreurs.

8. Déploiement sur un serveur de test et de production

Une fois le site web soigneusement testé dans un environnement local, l'étape suivante consiste à le déployer sur un serveur de test. C'est une action recommandée, car elle permet de réaliser d'autres tests dans des conditions similaires à l'environnement réel d'utilisation.

Après des tests réussis sur le serveur de test, la phase de déploiement sur le serveur de production suit. C'est la phase finale de la mise à niveau, au cours de laquelle le site web est lancé dans l'environnement cible et devient accessible à tous les utilisateurs. Il est important de s'assurer que ce processus est soigneusement planifié et exécuté. Cela permettra de réduire au minimum les temps d'arrêt et les perturbations potentielles de la disponibilité du site web.

Rappelez-vous de vérifier soigneusement vos exigences d'hébergement pour Drupal 10 une fois de plus avant de déployer sur un serveur de production, et assurez-vous que vous avez sauvegardé votre page web et votre base de données.

Liste des problèmes potentiels lors de la mise à niveau de Drupal

Vous pouvez rencontrer plusieurs problèmes différents lorsque vous mettez à niveau votre système vers Drupal 10. Jetez un œil à ma liste pour savoir à quoi vous attendre et comment y faire face.

1. Fonctions supprimées et marquées comme "obsolètes"

Dans Drupal 10, de nombreuses fonctionnalités qui fonctionnaient sous Drupal 9 ont été supprimées ou marquées comme "obsolètes". Cela peut causer des erreurs potentielles dans les journaux. La solution au problème est d'améliorer le code ou d'écrire des correctifs pour les modules dans lesquels ils se produisent. Un excellent outil pour aider dans ce processus est le module Drupal Upgrade Status décrit plus haut.

2. AccessCheck() requis

À partir de Drupal 10, toutes les requêtes d'entités de contenu doivent inclure un appel à la méthode ::accessCheck() avant d'être exécutées. C'est une exigence système pour améliorer la sécurité et le contrôle d'accès.

3. Fonction jQuery once

La fonction jQuery once a été supprimée du noyau de Drupal 10, mais elle est toujours présente dans de nombreux modules fournis par la communauté, ce qui peut entraîner des erreurs :

Uncaught TypeError: $(...).once is not a function

Solutions potentielles :

• Changez la bibliothèque core/jquery.once en core/once dans *.libraries.yml du module ou thème.
• Changez la fonction $.once() en once() dans les fichiers js.

4. Modules incompatibles avec Drupal 10

Un problème courant lors de la mise à niveau est l'incompatibilité des modules personnalisés et contribuer avec Drupal 10. J'ai décrit des solutions potentielles à de tels problèmes dans le paragraphe sur le module Drupal Upgrade Status.

5. Dépendances dans Composer

La tentative de mise à jour est souvent bloquée par des dépendances de divers modules dans Composer. Un outil utile pour résoudre ces conflits sera les commandes, que je décris plus en détail dans le paragraphe suivant.

Liste des commandes utiles

Pour simplifier vos actions dans Composer, j'ai préparé une liste de commandes pratiques à utiliser selon la situation.

1. Composer why-not (vous pouvez aussi utiliser composer prohibits)

Cette commande affiche une liste des dépendances empêchant l'actualisation. Exemple d'application :

composer why-not drupal/core ^10

2. Le drapeau --no-update

Vous permet d'ajouter une nouvelle dépendance à composer.json sans la mettre à jour et installer immédiatement de nouveaux paquets. Exemple d'application :

composer require 'drush/drush:^12' --no-update

3. Le drapeau -dry-run

Il vous permet de simuler le processus de mise à jour sans effectuer réellement de changements. Composer montrera les actions qui seront effectuées lors de la mise à jour mais ne fera aucun changement aux fichiers réels ou dépendances du projet. Exemple d'application :

composer update --dry-run

Mise à niveau de Drupal 8 ou 9 vers 10 - résumé

Le processus de mise à niveau vers Drupal 10, bien qu'il requière un certain effort et engagement, est un investissement qui peut apporter des avantages significatifs à votre solution CMS. Ce n'est pas seulement un pas en avant pour tirer parti des dernières fonctionnalités et améliorations, mais aussi un aspect essentiel pour améliorer la sécurité et amener votre site web aux derniers standards du web.

Espérons que ce guide vous facilitera le processus et vous fournira tous les outils nécessaires pour le faire efficacement et sans trop de difficulté. Cependant, si à un moment donné vous décidez que vous avez besoin d'une aide professionnelle pour mettre à niveau votre site web vers Drupal 10, nos développeurs expérimentés peuvent réaliser une mise à niveau complète ou vous assister dans la phase de migration de votre choix.