Rector dans une montée Symfony : ce qu'il fait, ce qu'il ne fait pas

Rector revient dans toutes les discussions sur les montées de version PHP, et il mérite sa place : la documentation Symfony elle-même le cite. Mais le raccourci « Rector fait la migration » coûte cher, parce qu'il fait naître une attente que l'outil ne prétend nulle part satisfaire. Cette page s'en tient à ce que les deux projets documentent.

Ce que Rector est, techniquement

Le dépôt officiel le présente comme un outil qui met à niveau et refactorise instantanément le code PHP d'une application, sur deux terrains : les montées de version, avec une couverture annoncée de PHP 5.3 à 8.5 et des jeux de règles dédiés à des projets majeurs dont Symfony, PHPUnit et Doctrine ; et le refactoring continu, branché sur l'intégration continue.

Le fonctionnement se résume à trois choses. On déclare dans un fichier `rector.php` soit des règles unitaires, soit des `sets`, c'est-à-dire des groupes de règles préparés. On lance l'outil en mode `--dry-run`, qui affiche le diff de ce qu'il changerait sans rien écrire. On relance sans l'option pour appliquer. Le catalogue complet des règles est consultable en ligne, et c'est la seule façon fiable de savoir si votre cas est couvert : personne ne peut le déduire à votre place.

Ce que les projets reconnaissent eux-mêmes comme limites

Le premier tempérament vient de Symfony. Son guide de montée majeure mentionne Rector, en le qualifiant de projet tiers qui automatise la mise à niveau et le refactoring de projets PHP, et en précisant qu'il inclut « certaines règles » pour corriger « certaines » dépréciations Symfony automatiquement. Les deux restrictions sont dans le texte original. Ce n'est pas une réserve polie, c'est la description exacte du périmètre.

Le second vient de Rector, qui publie une section de limitations connues dans son propre dépôt. Trois points en sortent, et ils ont des conséquences pratiques immédiates. L'outil s'appuie sur un arbre syntaxique abstrait, qui ne connaît pas les espaces : le code réécrit ressort mal formaté, en PHP comme dans les blocs de documentation. Le projet en tire la conséquence explicitement, votre dépôt doit disposer d'un outil de style et d'un jeu de règles de formatage pour rattraper la sortie. Enfin, sur les fichiers mêlant PHP et HTML, la documentation recommande une vérification manuelle du fichier après application.

Où passe la frontière

Cette frontière n'est pas une opinion sur Rector, c'est la définition d'un réécrivain fondé sur la syntaxe. Il applique des transformations dont la correction est décidable en lisant le code. Tout ce qui exige de connaître l'intention, la règle de gestion ou le contrat implicite entre deux modules sort de son domaine, quel que soit le nombre de règles disponibles.

Comment le lancer sans dégrader le dépôt

• Partez d'un répertoire de travail propre : un diff de plusieurs centaines de fichiers mélangé à du travail en cours n'est plus relisible.
• Commencez toujours par `--dry-run` et lisez le diff. Le mode d'application n'est pas le mode d'exploration.
• Appliquez un jeu de règles à la fois, avec un commit par jeu. La revue redevient possible et le retour en arrière est ciblé.
• Lancez le formateur du projet juste après, dans un commit séparé, pour que le bruit de mise en forme ne masque pas les changements de fond.
• Vérifiez à la main les fichiers mêlant PHP et balisage, comme le projet le recommande.

Ce que Rector ne remplace pas

Rector transforme du code. Il ne dit rien sur le fait que le comportement soit préservé : c'est une réécriture syntaxique, pas une preuve. La seule chose qui vous apprendra qu'une application fait toujours ce qu'elle faisait, c'est de l'exécuter et de comparer le résultat attendu au résultat obtenu. Un outil de réécriture sans dispositif de vérification derrière ne fait pas gagner du temps, il déplace le moment où l'on découvre le problème.

Questions fréquentes