Drupal Rector : votre allié pour les mises à jour majeures de Drupal

Avec la sortie de la nouvelle version de Drupal au mois d’août, nous sommes nombreux à vouloir profiter de ces nouvelles mises à jour. Mais comme souvent, nous mettons du temps à passer le cap, soit par manque de temps, soit parce qu’il faut revoir une partie du code qui est daté. Ce qui n’est pas des plus passionnant.

Pour faciliter les montées de version de Drupal, personnellement j’utilise l’outil Drupal Rector. Cet outil m’aide à repérer les modifications à apporter au code existant, me propose des changements, corrige le code mort, etc.

Curieux d’en savoir plus ? Dans cet article, je vous explique comment l’installer, le configurer et l’utiliser dans vos projets Web. Mais avant de passer à la partie technique, je vous propose une petite présentation.

Qu’est-ce que Drupal Rector ?

Drupal Rector est un outil open-source apparu en 2020 initialement pour la version 8 du CMS Drupal. Il est basé sur Rector PHP et son but est d’automatiser la mise à niveau de code PHP déprécié entre différentes versions de Drupal.

Comment est né l’outil Drupal Rector ?

Souvent négligé par les développeurs, Rector PHP est un puissant outil d’automatisation des mises à niveau de code PHP. Développé par @VotrubaT, il est considéré comme l’un des projets les plus utiles.

Sur les bases de ce précédent outil, Drupal Rector a été développé par Palantir.net dans le but d’atteindre un double objectif :

• Simplifier la transition entre versions majeures de Drupal grâce à l’automatisation de la mise à niveau de code PHP déprécié (tâche auparavant manuelle et chronophage).
• Réduire les risques d’erreurs lors des mises à jour en permettant aux développeurs de se concentrer sur les aspects plus complexes de la mise à jour.

Drupal Rector libère donc le développeur d’une grande partie du processus de mise à jour du code pour assurer sa compatibilité avec les dernières versions de Drupal.

🤔 FOCUS - Qui est Palantir.net ? Palantir.net est le contributeur majeur de l’écosystème Drupal. Il a transformé Drupal Rector en un outil incontournable pour les développeurs. Lancé en 2020 pour la transition de Drupal 8 à 9, le projet s’est rapidement étendu à la préparation pour Drupal 10. En collaboration avec Acquia, l’équipe a réussi à couvrir 95 % des utilisations d’API dépréciées dans les projets Drupal 9, facilitant ainsi une mise à niveau largement automatisée vers Drupal 10.
Cette innovation a valu à Palantir.net le prix Acquia Engage « Open Source Giants Award » en 2021, témoignant de l’impact significatif de Drupal Rector sur la communauté.

Comment fonctionne-t-il ?

Avec Drupal Rector, la mise à jour de votre code devient un processus automatisé et structuré qui s’appuie sur 3 étapes :

• Analyse : l’outil analyse le code PHP existant et le convertit en une structure de données appelée Arbre de Syntaxe Abstraite (AST).
• Transformation : sur cet AST, il applique un ensemble de règles de mise à niveau.
• Sauvegarde : l’outil sauvegarde toutes les modifications dans les fichiers PHP d’origine.

Quelles sont ses capacités ?

Dans un projet Web, Drupal Rector est capable de renommer des classes, des méthodes, des propriétés, des espaces de noms ou des constantes. Il peut également mettre à niveau le code de PHP 5.3 à PHP 8.4 et mettre à niveau le code entre deux versions majeures de Symfony.

Quels sont ses avantages et les points d’attention à avoir ?

Depuis que je l’utilise, Drupal Rector m’a permis de repenser les mises à jour des projets Web. Je vous partage les 3 grands bénéfices que j’en retire :

1. Gain de temps : automatise une grande partie des corrections nécessaires.
2. Réduction des erreurs : minimise les oublis et les erreurs manuelles.
3. Apprentissage : aide à comprendre les changements entre les versions de Drupal.

Cependant, avec la pratique, je vous conseille vivement de :

1. Toujours vérifier les changements proposés avant de les appliquer.
2. Être conscient que certains problèmes peuvent nécessiter une intervention manuelle.

Voilà, j’ai terminé de vous le présenter, passons maintenant à la partie plus technique.

Comment installer et configurer Drupal Rector ?

L’installation de Drupal Rector se fait simplement via une commande « Composer » :

NB : Drupal Rector étant un outil d’aide au développement, il est plus pertinent d’indiquer à Composer de le classer dans les packages de développement (paramètre « --dev » de la commande ci-dessus).

Un fois installé, vous devez maintenant le configurer. Pour cette étape, vous allez créer un fichier « rector.php » à la racine de votre projet. Avant de rentrer dans les détails, voici un exemple global de la configuration du fichier.

declare(strict_types=1);

use DrupalRector\Set\Drupal10SetList;
use DrupalRector\Set\Drupal8SetList;
use DrupalRector\Set\Drupal9SetList;
use Rector\Config\RectorConfig;

return static function (RectorConfig $rectorConfig): void {
	$rectorConfig->sets([
		Drupal8SetList::DRUPAL_8,
		Drupal9SetList::DRUPAL_9,
		Drupal10SetList::DRUPAL_10,
	]);

	$drupalFinder = new \DrupalFinder\DrupalFinderComposerRuntime();
	$drupalRoot = $drupalFinder->getDrupalRoot();
	$rectorConfig->autoloadPaths([
		$drupalRoot . '/core',
		$drupalRoot . '/modules',
		$drupalRoot . '/profiles',
		$drupalRoot . '/themes'
	]);

	$rectorConfig->skip([
		'*/upgrade_status/tests/modules/*',
		'*/node_modules/*',
		'*/vendor/*',
	]);

	$rectorConfig->fileExtensions(['php', 'module', 'theme', 'install', 'profile', 'inc', 'engine']);
	$rectorConfig->importNames(true, false);
	$rectorConfig->importShortClasses(false);
};

Comment se structure le fichier « rector.php » ?

Le fichier « rector.php » est constitué de plusieurs éléments :

• les règles de code à suivre,
• les chemins d’autoload pour indiquer où se situe le code,
• les exclusions, etc.

Maintenant, je vous propose de voir en détail les différents éléments de configuration.

La configuration des ensembles de règles

Cette première configuration est importante. Elle indique à Drupal Rector d’appliquer les règles de mise à jour pour Drupal 8, 9 et 10. Cela signifie que Rector va :

1. Identifier et corriger le code obsolète de Drupal 8.
2. Appliquer les changements nécessaires pour la compatibilité avec Drupal 9.
3. Et préparer le code pour la dernière version de Drupal 10.

En incluant ces trois ensembles, vous assurez une mise à jour complète et progressive de votre code.

NB : À l’heure où nous rédigeons cet article, il n’existe pas encore de liste de règles propre à Drupal 11. Pour faciliter votre mise à jour, nous vous conseillons d’utiliser conjointement Drupal Rector et le module Drupal Upgrade Status. Je vous conseille donc de lire notre article de blog : Comment migrer votre site Web de Drupal 10 à Drupal 11 ?

La détection de l’installation Drupal et la configuration des chemins d’autoload

Ici, on va utiliser DrupalFinder pour localiser automatiquement le répertoire de base de l’installation Drupal puis, à partir de ce répertoire, définir les dossiers principaux de Drupal que Rector doit analyser :
/core : le cœur de Drupal
/modules : tous les modules (contribués et personnalisés)
/profiles : les profils d’installation
/themes : les thèmes

Cela garantit que Drupal Rector examine tous les fichiers PHP pertinents dans votre installation Drupal.

Les exclusions

Cette configuration est également importante, car elle évite la modification de fichiers tiers par Drupal Rector. Elle exclut donc :

1. Les modules de test du module communautaire Upgrade Status (ce module permet de déterminer le pourcentage de compatibilité de son site avec la prochaine version majeure de Drupal. Il est souvent utilisé en association avec Drupal Rector).
2. Les dépendances Node.js.
3. Les dépendances « Composer ».

Les extensions de fichiers

Cette ligne est spécifique à Drupal. Elle indique à Drupal Rector de traiter non seulement les fichiers .php standard, mais également les types de fichiers spécifiques à Drupal comme les fichiers avec l’extension .module, .theme, etc.

Il est essentiel de s’assurer que tous les fichiers Drupal pertinents soient pris en compte pour l’analyse.

La configuration des importations

Ces deux lignes configurent la façon dont Drupal Rector gère les espaces de noms et les importations de classes :

• importNames(true, false) indique à Drupal Rector d'ajouter des déclarations « use » pour les noms de classe pleinement qualifiés, mais sans les raccourcir.
• importShortClasses(false) empêche Drupal Rector de raccourcir les noms de classe importés. Par exemple, il ne transformera pas \Drupal\Core\Form\FormStateInterface en use FormStateInterface.

Cette dernière configuration assure que Drupal Rector peut efficacement analyser et mettre à jour le code Drupal tout en respectant les conventions et la structure spécifique de Drupal.

Comment utiliser Drupal Rector ?

Maintenant que Drupal Rector est configuré, voyons comment l’utiliser. Commencez par exécuter la commande suivante pour analyser le répertoire des modules custom :

Ici, vous avez certainement remarqué l’option « --dry-run ». Cette option permet de visualiser les changements proposés sans les appliquer immédiatement. Vous pouvez donc vérifier puis valider les modifications avant de les appliquer.

Vous noterez, qu’il est également possible de cibler un répertoire ou un module précis.

Vous avez effectué les vérifications et les changements proposés par Drupal Rector vous conviennent ? Maintenant vous pouvez donc appliquer les changements. Pour ce faire, il vous suffira d’exécuter la même commande, mais sans l’option « --dry-run ».

Je vous ai fait une capture d’écran d’exemple de modification avec l'option « --dry-run ».

Les options avancées de Drupal Rector

Drupal Rector offre une variété de règles et d'ensembles de règles (sets) qui peuvent être appliqués à votre code.

Ajouter des sets supplémentaires à son analyse de code

En plus des sets spécifiques à Drupal définis par DrupalRector, vous pouvez aussi utiliser des sets généraux issus de Rector pour améliorer la qualité globale de votre code.

La liste des sets proposés par Rector est disponible ici.

Voici par exemple quelques options supplémentaires que vous pouvez ajouter à votre configuration :

• SetList::DEAD_CODE - Ce set permet d’identifier et de supprimer le code mort. En d’autres termes, le code qui n’est jamais exécuté ou qui n’a aucun effet. Un code mort peut inclure des variables non utilisées, des conditions toujours vraies ou fausses, ou des fonctions jamais appelées.
• SetList::CODE_QUALITY - Ce set applique diverses règles pour améliorer la qualité générale du code. Il peut s’agir, par exemple, de la simplification des expressions complexes, de la correction des problèmes de typage, ou encore de l’optimisation des structures de contrôle.

En plus des règles spécifiques à Drupal, Drupal Rector peut également être configuré pour mettre à jour votre code PHP vers des versions plus récentes. Voici un exemple de configuration possible :

Vous remarquez que cette configuration ajoute un ensemble de règles supplémentaires à Drupal Rector.

• LevelSetList::UP_TO_PHP_81 – Dans ce cas précis, cet ensemble de règles applique toutes les modifications nécessaires pour rendre votre code compatible avec PHP 8.1.

Mais qu’est-ce que ça signifie concrètement ? Je vous ai listé les avantages de cette configuration :

• La mise à niveau du code PHP. Drupal Rector appliquera automatiquement les changements nécessaires pour que votre code soit compatible avec PHP 8.1. Cela inclut l'utilisation de nouvelles fonctionnalités et la suppression de pratiques obsolètes.
• La compatibilité avec Drupal. C’est particulièrement utile pour les projets Drupal. En effet, Drupal 10 nécessite PHP 8.1 ou supérieur. Cette configuration vous aide à préparer votre code non seulement pour Drupal 10, mais aussi pour la version de PHP qu'il requiert.
• Les améliorations de performance et de sécurité. Les versions plus récentes de PHP offrent souvent de meilleures performances et des fonctionnalités de sécurité améliorées. Cette mise à niveau peut donc bénéficier à votre projet au-delà de la simple compatibilité.
• Enfin, la préparation pour l'avenir. En mettant à jour votre code vers PHP 8.1, vous préparez également votre projet pour des mises à niveau futures de Drupal et de PHP.

Pour résumer, au-delà de la simple compatibilité avec les nouvelles versions de Drupal, l’utilisation de ces sets supplémentaires peut grandement améliorer la lisibilité et la maintenabilité de votre code.

Ajouter des règles supplémentaires à votre analyse de code

Le chapitre précédent décrit comment ajouter tout un ensemble de règles (set) à votre analyse de code. Sachez que si vous ne souhaitez profiter que de quelques règles spécifiques, il est aussi possible d’ajouter des règles de manière individuelle en rajoutant la section suivante à votre fichier rector.php :

Une liste des règles de Drupal Rector avec exemples est disponible ici.

Attention, soyez tout de même prudent lorsque vous utilisez ces règles supplémentaires. Il peut arriver qu’elles modifient la logique de votre code de manière inattendue. Je vous recommande donc de toujours :

1. Exécuter Drupal Rector avec l’option « --dry-run » pour examiner les changements proposés.
2. Avoir une suite de tests complète pour votre code. L’objectif de ces tests sera de vous assurer que les modifications n'engendrent pas de régressions.
3. Examiner attentivement chaque changement proposé, en particulier pour les règles qui ne sont pas spécifiques à Drupal.

En ajustant ces options, vous pouvez personnaliser Drupal Rector pour qu'il réponde au mieux aux besoins spécifiques de votre projet.

Ce qu’il faut retenir, c’est que Drupal Rector est un outil précieux pour tout développeur Drupal confronté à des mises à jour majeures. En le configurant bien, vous gagnerez du temps dans la mise à jour de votre code, vous limiterez les erreurs et vous faciliterez la transition vers les versions majeures du CMS.

Néanmoins, Drupal Rector reste un outil. Avant d’appliquer toutes les modifications proposées, je vous conseille de vérifier les changements et de garder en tête que certaines mises à niveau nécessiteront une intervention manuelle.

J’espère que cet article vous aidera pour votre prochaine migration vers Drupal 10 ou 11. Pour compléter cet article, je vous propose un autre article sur le même thème : Mise à jour de Drupal 9 vers Drupal 10 : le mode d'emploi

Pour en savoir plus :

• Article du blog Drupalize.me d’avril 2020
• Github Drupal Rector
• Github Rector

Crédit photo : Dragos Condrea