Guide étape par étape pour mettre à niveau Drupal 9 vers Drupal 10

Le processus de mise à niveau d’un projet Drupal de 9 à 10 peut être une tâche un peu difficile. Ce blog couvre les directives de base qui vous aideront à mettre à niveau les versions majeures de projets simples ou complexes.

1. Vérifiez les pré-requis

Exigences de la plateforme :

Drupal 10 nécessite PHP 8.1+. Ces mises à jour de la plateforme doivent être effectuées avant de démarrer le processus de mise à niveau. Voici un aperçu des exigences complètes pour php, serveur, base de données, etc. – https://www.drupal.org/docs/getting-started/system-requirements

Version Drush :

Si Drush est installé, vous devez vérifier le Version recommandée. Drupal 10 nécessite drush 11 ou version ultérieure. Voici la commande que vous pouvez suivre pour installer Drush 11 –

 composer require 'drush/drush:^11' -W

CONSEIL: Certains développeurs préfèrent le supprimer temporairement et le réinstaller plus tard.

2. Préparation à la mise à niveau D10

Installer Statut de mise à niveau module

Cela fournit un bon aperçu de la santé de la mise à niveau du site et permet de vérifier les dépréciations et la compatibilité des modules/projets de contribution. Voici les commandes pour installer et activer ce module :

composer require 'drupal/upgrade_status:^4.1'
drush en upgrade_status

Consultez le rapport à la page – /admin/reports/état-de-mise à niveau

Mettez à jour l’ensemble du site (modules principaux et contrib) vers la dernière version 9.4 ou, au mieux, 9.5.

Vous pouvez modifier manuellement le fichier composer.json et mettre à jour la version des packages Drupal/core-* vers la version recommandée (par exemple 9.5.11), puis exécuter la commande suivante pour mettre à jour tous les modules vers leur dernière version d9 :

composer update --with-all-dependencies
drush updb
drush cr

Assurez-vous maintenant que le site fonctionne correctement.

Traiter tous les modules ou thèmes obsolètes utilisé sur votre site.

Les modules de base supprimés de d10 sont :

• Agrégateur
• CKEditor (CKEditor5 maintenant)
• Couleur
• HAL
• Edition rapide
• RDF

Les thèmes principaux supprimés du D10 sont :

• Bartik
• Chic
• Sept
• Écurie

Il existe trois options pour gérer ces problèmes : –

Option 1. Désinstallez-le simplement s’il ne sert à rien sur votre site.

Option 2. Basculez vers les différents projets pris en charge s’ils sont disponibles dans le noyau. Par exemple, changez Bartik en Olivero, sept en Claro, ckeditor en ckeditor5

Option 3. Si vous ne pouvez pas désinstaller/changer, installez la version contribuée correspondante depuis drupal.org

Par exemple, si vous avez un thème personnalisé ou contribué qui dépend de classy (supprimé du noyau d10), installez le thème Classy contribué avec Composer :

composer require “drupal/classy:^1.0”

Migration de CKEditor de 4 à 5

• Activez CKEditor5.
• Assurez-vous que vos plugins CKEditor ont des versions CKEditor 5 (ou supprimez ceux qui n’en ont pas)
• Accédez à Création de contenu > Formats de texte et éditeurs à l’aide du menu d’administration. Dans la colonne Editeur de texte, vous pouvez indiquer quels formats de texte utilisent CKEditor.
• Pour chaque format de texte qui utilise CKEditor, sélectionnez Configurer. Sous Éditeur de texte, sélectionnez CKEditor. Vous pouvez voir des messages d’état vous informant de ce qui a changé.
• Effectuez les étapes ci-dessus pour tous les formats de texte à l’aide de CKEditor.
• Vérifiez que CKEditor 5 fonctionne correctement et désinstallez CKEditor.

Traitez la section « Supprimer » sur la page d’état de la mise à niveau (/admin/reports/upgrade-status).

Pour supprimer les modules/thèmes désinstallés, supprimez simplement leurs entrées du fichier composer.json et exécutez la mise à jour du compositeur, OU vous pouvez exécuter la commande composer remove pour chacun.

Note: Si cette liste contient un module/thème absent dans composer.json, vous devrez alors le supprimer manuellement du système de fichiers.

Traitez la section « Mise à jour » sur la page d’état de la mise à niveau.

Assurez-vous que tous les modules/thèmes/profils de contribution sont à la dernière version stable de D10. Exécutez simplement la commande composer require pour récupérer la dernière version de la version stable D10. Par exemple:-

composer require 'drupal/acquia_search:^3.1' -W 

Une fois cette étape répétée pour tous les modules ici et analysée à nouveau, il ne restera plus rien dans cette section.

Traitez les modules de la section « Collaborer avec le responsable » sans version compatible D10 disponible sur drupal.org.

• Assurez-vous sur la page du projet drupal.org qu’il s’agit de la dernière version du module compatible D10. Sinon, exécutez composer require & drush updb.
• Sinon, recherchez un correctif dans la file d’attente des problèmes pour la compatibilité D10 ou créez votre propre correctif. Installez le plugin cweagans et ajoutez un patch de compatibilité dans composer.json.

composer require cweagans/composer-patches

Installer le compositeur indulgent plugin et ajoutez le module corrigé à la liste autorisée afin que le compositeur puisse l’adapter à la mise à niveau D10.

Pour cela, exécutez la commande install et spécifiez le module requis (par exemple drush_delete) : –

composer require mglaman/composer-drupal-lenient
composer config --merge --json extra.drupal-lenient.allowed-list '["drupal/drush_delete"]

Après avoir exécuté les commandes ci-dessus, la section indulgente sera ajoutée dans composer.json :-

Conseil: Assurez-vous d’avoir ajouté TOUS les modules corrigés à composer-drupal-lenient. Si vous en manquez ne serait-ce qu’une seule, le compositeur ignorera toutes vos demandes de clémence, ce qui peut être très déroutant.

Gérer les modules qui n’ont pas une seule version compatible avec les D9 et D10

Pour résoudre ce problème, Composer nécessite les deux versions requises par D9 ainsi que D10 pour permettre au module d’être automatiquement mis à niveau lorsque vous mettez à niveau le noyau Drupal. Par exemple-

composer require drupal/csv_serialization:^3.0 || ^4.0

Mettre à jour les modules et thèmes personnalisés dans la section « Scan »

• Mettez à jour la version requise dans le fichier info.yml de tous ces modules pour la compatibilité D10.

Eg: 
Change from 
core_version_requirement: ^9
To
core_version_requirement: ^9 || ^10

• Analysez tous les éléments et résolvez les erreurs de dépréciation soit manuellement selon les suggestions, soit à l’aide du plugin Drupal rector.

Pour minimiser les efforts manuels, installez le plugin rector pour la correction automatique du code obsolète :

composer require --dev palantirnet/drupal-rector
cp vendor/palantirnet/drupal-rector/rector.php .
vendor/bin/rector process modules/custom/[MODULE/THEME_NAME] --dry-run

Note: Exécutez sans « –dry-run » une fois que vous avez examiné les modifications qui seraient apportées.

3. Démarrez la mise à niveau du D10

À présent, le site devrait être prêt pour la mise à jour D10. Vous pouvez le vérifier à partir du pourcentage de préparation affiché sur la page État de la mise à niveau.

• Modifiez le fichier composer.json et mettez à jour la version des packages Drupal/core-* vers ^10 (ou toute version D10 spécifique de votre choix, par exemple 10.1.8).

• Testez la mise à jour avant d’effectuer la mise à jour proprement dite :

composer update --with-all-dependencies --dry-run

• En cas d’échec, exécutez la commande suivante pour vérifier les dépendances interdisant la mise à niveau :

composer why-not drupal/core ^10 OR composer update "drupal/core:^10" -W --dry-run

Une fois le problème identifié, résolvez-le et exécutez à nouveau la commande test update jusqu’à ce qu’elle s’exécute correctement.

• Exécutez la mise à jour réelle sans indicateur d’exécution à sec, exécutez les mises à jour de la base de données et videz le cache.

composer update --with-all-dependencies 
drush updb
drush cr

Et le site est désormais entièrement mis à jour vers la version Drupal 10 !!

Vérification des correctifs.

Vérifiez que tous les anciens correctifs ajoutés dans le fichier composer.json ont été appliqués avec succès.

Recherchez chaque appel de jquery.once() dans les modules/thèmes personnalisés et mettez-le à jour avec la nouvelle fonction javascript once.

De plus, si vous avez une dépendance à la bibliothèque core/jquery.once dans votre fichier library.yml, changez-la avec la bibliothèque core/once.

Conseil: Désactivez d’abord l’agrégation si elle est activée avant d’effectuer cette étape.

Testez l’intégralité du site

Vérifiez toutes les fonctionnalités et assurez-vous que le site fonctionne correctement. À chaque chargement de page dans le navigateur, consultez les journaux Drupal pour détecter les erreurs et/ou les avertissements. Recherchez également des erreurs dans la console du navigateur. Réparez-les si nécessaire.

Quelques erreurs PHP courantes rencontrées en raison d’un code PHP incompatible :

• ->accèsVérifier() doit maintenant être explicitement spécifié lors de l’utilisation d’une requête d’entité de contenu.
• Sortie de brindille l’utilisation de {% spaceless %} est remplacée par {% apply spaceless %}.
• Prise en charge de la clause « if » supprimée des instructions « for » dans les fichiers twig.
• Les méthodes de test setUp() nécessitent un type de retour void (c’est-à-dire une fonction protégée setUp() : void

Résolvez ces problèmes selon les suggestions dans les enregistrements de modifications.

Quelques problèmes rencontrés lors du processus de mise à niveau :

1. Si la mise à jour du compositeur génère une erreur, «Vos besoins n’ont pas pu être résolus en un ensemble de packages installables.». Il peut y avoir deux raisons à cela : –

• Un ou plusieurs de vos modules contribués ne sont pas compatibles D10. Pour résoudre ce problème, identifiez le module coupable dans l’erreur du compositeur, visitez la page du projet, recherchez la dernière version stable de D10 et installez-la. Par exemple

composer require drupal/MODULE_NAME:^2.0.0-rc1 --no-update

• Certaines des dépendances de votre projet ne sont pas à jour avec leur dernière version pour les mises à jour principales. Pour résoudre ce problème, suivez les étapes ici.

2. Certains utilitaires comme la console Drupal ou drush peuvent gêner le processus de mise à niveau de base. Pour résoudre ce problème, vous pouvez le supprimer complètement avant la mise à jour et le réinstaller après la mise à jour. Par exemple

composer remove drupal/console --no-update
composer remove drush/drush --no-update

3. Si vous utilisez le module Advaggl’intégralité du JS pourrait tomber en panne sur votre site après la mise à niveau D10.

L’une des raisons possibles est l’utilisation de Jsqueeze pour réduire JS. Basculez-le sur Jshrink ou un autre mode comme Jsqueeze est abandonné maintenant.

Conclusion

Grâce à ce blog, nous avons appris comment rendre les éléments compatibles avec D10 tout en utilisant Drupal 9. Cela comprenait l’examen des modules personnalisés et contribués pour vérifier la compatibilité. Une fois que tout est prêt, nous avons mis à jour le noyau Drupal. Nous avons également partagé quelques problèmes courants rencontrés lors de la mise à niveau et leurs solutions.

J’espère que vous ne trouverez pas ce processus si difficile la prochaine fois. Consultez nos autres articles de blog pour plus d’informations.