WPCS 3.0 : ce qui change dans votre configuration PHPCS

Le paquet wp-coding-standards/wpcs, utilisé depuis des années sur la quasi-totalité des projets WordPress qui appliquent un standard de code automatisé, a connu cette année sa refonte la plus importante avec la sortie de la version 3.0. Le changement le plus visible : ce qui était un seul dépôt Git est désormais réparti en plusieurs paquets Composer distincts, chacun maintenu séparément. Sur plusieurs projets clients, cette mise à jour a cassé des pipelines CI qui fonctionnaient parfaitement depuis des mois, le temps de comprendre exactement ce qui avait changé.

Cet article détaille la nouvelle organisation du paquet, la marche à suivre pour migrer un phpcs.xml.dist existant, et les pièges rencontrés sur nos projets lors de cette transition.

Ce qui change concrètement

Avant WPCS 3.0, un seul dépôt fournissait à la fois le moteur de règles spécifiques WordPress et ses dépendances internes. La version 3.0 sépare ces responsabilités, avec en particulier une dépendance désormais explicite vers PHPCSUtils et PHPCSExtra, deux bibliothèques d’utilitaires partagées par plusieurs standards de codage dans l’écosystème PHP, pas seulement WordPress. Cette séparation permet à l’équipe de maintenance de faire évoluer ces briques indépendamment, et surtout d’étendre la compatibilité de WPCS aux versions récentes de PHPCS, qui avaient évolué plus vite que l’ancien mécanisme de dépendances ne le permettait.

Mettre à jour composer.json

La mise à jour se fait via Composer comme d’habitude, mais avec une vigilance particulière sur les versions minimales de PHP requises, WPCS 3.0 ayant relevé cette exigence par rapport aux versions précédentes :

composer require --dev wp-coding-standards/wpcs:"^3.0" --with-all-dependencies

L’option --with-all-dependencies est importante : elle autorise Composer à mettre à jour PHPCS lui-même et les paquets liés si nécessaire, ce qui est généralement indispensable pour satisfaire les nouvelles contraintes de version de WPCS 3.0.

Vérifier la compatibilité de votre phpcs.xml.dist

La bonne nouvelle : pour la grande majorité des projets, le fichier phpcs.xml.dist existant continue de fonctionner sans modification, les noms des rulesets (WordPress-Core, WordPress-Extra, WordPress-Docs) restant inchangés. Sur nos projets, les seuls ajustements nécessaires ont concerné quelques sniffs renommés ou déplacés entre les paquets, notamment certains sniffs génériques auparavant fournis par WPCS lui-même et désormais issus directement de PHPCSExtra.

<?xml version="1.0"?>
<ruleset name="Mon Agence">
    <file>.</file>
    <exclude-pattern>*/vendor/*</exclude-pattern>

    <arg name="extensions" value="php"/>
    <arg value="sp"/>

    <rule ref="WordPress-Extra"/>
    <rule ref="WordPress.WP.I18n">
        <properties>
            <property name="text_domain" type="array" value="mon-plugin"/>
        </properties>
    </rule>
</ruleset>

Ce fichier n’a nécessité aucune modification sur nos projets après la montée en version. La commande suivante permet de repérer immédiatement un sniff introuvable si votre configuration référence explicitement un nom de règle qui a changé :

vendor/bin/phpcs -i

Vérifier la matrice de CI

WPCS 3.0 exige une version minimale de PHP plus récente pour l’outillage lui-même que ce qui était toléré auparavant, indépendamment de la version de PHP ciblée par votre projet. Sur un pipeline GitHub Actions qui exécutait encore PHPCS sous une version ancienne de PHP par simplicité, cette contrainte a nécessité de séparer explicitement la version de PHP utilisée pour lancer les outils de qualité de celle utilisée pour exécuter les tests PHPUnit :

jobs:
  qualite:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
      - run: composer install
      - run: vendor/bin/phpcs

Séparer ce job de celui qui fait tourner PHPUnit sur plusieurs versions de PHP simplifie la lecture des échecs : un échec PHPCS ne se mélange plus avec un échec de compatibilité PHP ancienne dans le même rapport.

Ce que nous avons appris de cette migration

• Testez la mise à jour sur une branche dédiée avant de la généraliser à tous les projets d’un coup, même si le changement paraît mineur en surface.
• Séparez, si ce n’est pas déjà fait, le job CI de qualité de code (PHPCS, PHPStan) du job d’exécution des tests PHPUnit sur plusieurs versions de PHP.
• Relisez le journal des modifications officiel de WPCS avant de monter en version sur un projet avec un phpcs.xml.dist très personnalisé, qui référence des sniffs spécifiques par leur nom complet.

Sur nos projets, cette migration nous a rappelé une règle simple : un outillage de qualité de code fige souvent trop longtemps une version dans un composer.lock, jusqu’au jour où une mise à jour de sécurité ailleurs force la main. Mieux vaut planifier ces montées de version régulièrement, plutôt que de les subir toutes en même temps.

En résumé

WPCS 3.0 réorganise en profondeur ses dépendances internes, sans pour autant bouleverser la configuration visible côté utilisateur pour la majorité des projets. L’essentiel du travail de migration consiste à mettre à jour Composer avec les bonnes contraintes de version, vérifier que la version de PHP utilisée pour lancer PHPCS en CI satisfait les nouvelles exigences, et repasser en revue les rares sniffs personnalisés référencés explicitement par leur nom. Un chantier limité, mais qui mérite d’être planifié plutôt que découvert au détour d’un échec de pipeline.