Configurer PHPCS et les WordPress Coding Standards sur un projet d’agence

Dans une agence qui fait tourner plusieurs développeurs sur les mêmes plugins et thèmes, la cohérence du code compte presque autant que sa correction. Un fichier où chacun indente à sa façon, mélange guillemets simples et doubles, ou oublie l’échappement des sorties, devient vite un fichier que personne n’a envie de reprendre. PHP CodeSniffer, combiné aux WordPress Coding Standards, automatise cette relecture et la rend objective.

Cet article détaille l’installation de PHPCS sur un projet WordPress, la configuration d’un fichier phpcs.xml.dist partagé par toute l’équipe, et les arbitrages à faire entre les différents rulesets disponibles.

Installer PHPCS et WPCS via Composer

La méthode recommandée en 2020 passe par Composer, avec l’installeur dealerdirect/phpcodesniffer-composer-installer qui enregistre automatiquement le chemin des règles WordPress auprès de PHPCS :

composer require --dev squizlabs/php_codesniffer
composer require --dev wp-coding-standards/wpcs
composer require --dev dealerdirect/phpcodesniffer-composer-installer

Une fois l’installation terminée, la commande suivante confirme que le standard WordPress est bien détecté :

vendor/bin/phpcs -i

Vous devez voir apparaître WordPress, WordPress-Core, WordPress-Extra et WordPress-Docs dans la liste des standards disponibles.

Comprendre les différents rulesets WPCS

Le paquet wp-coding-standards/wpcs ne fournit pas un seul ruleset, mais plusieurs, à combiner selon les besoins du projet :

• WordPress-Core : les règles strictes du cœur WordPress lui-même (indentation, espacement, conventions de nommage des fonctions).
• WordPress-Extra : des règles supplémentaires recommandées pour les plugins et thèmes, notamment autour de la sécurité (échappement des sorties, validation des entrées, nonces).
• WordPress-Docs : des règles sur la documentation en ligne, au format DocBlock.

La plupart des agences ne suivent pas WordPress-Core à la lettre, car ses conventions de style diffèrent souvent de celles adoptées en interne. Le choix le plus courant consiste à s’appuyer sur WordPress-Extra, qui inclut déjà l’essentiel des vérifications de sécurité sans imposer toutes les contraintes stylistiques du cœur.

Écrire un phpcs.xml.dist pour toute l’équipe

Plutôt que de configurer PHPCS en ligne de commande à chaque exécution, un fichier phpcs.xml.dist à la racine du projet fixe la configuration pour tout le monde :

<?xml version="1.0"?>
<ruleset name="Mon Agence - Plugin Client">
    <description>Règles de codage pour le plugin client</description>

    <file>.</file>
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
    <exclude-pattern>*/tests/*</exclude-pattern>

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

    <rule ref="WordPress-Extra">
        <exclude name="WordPress.Files.FileName"/>
    </rule>

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

Ce fichier commis dans le dépôt garantit que chaque développeur, et chaque exécution en CI, applique exactement les mêmes règles. Le nom phpcs.xml.dist plutôt que phpcs.xml permet à chacun de garder une copie locale phpcs.xml non versionnée pour des ajustements personnels, sans casser la configuration commune.

Exclure intelligemment les faux positifs

Certaines règles de WordPress-Extra produisent des avertissements peu pertinents selon le contexte du projet, par exemple WordPress.Files.FileName qui impose une convention de nommage de fichiers parfois incompatible avec un autoloader PSR-4. Les exclure explicitement, avec une justification en commentaire, vaut mieux que de les ignorer silencieusement à chaque lecture du rapport.

Lancer l’analyse et corriger automatiquement

La commande de base reste simple :

vendor/bin/phpcs

Pour les erreurs qui peuvent être corrigées automatiquement (espacement, guillemets, alignement), phpcbf (PHP Code Beautifier and Fixer) fait gagner un temps considérable :

vendor/bin/phpcbf

Attention toutefois : phpcbf modifie les fichiers directement. Il vaut mieux le lancer sur une copie de travail propre, avec les changements déjà commités, pour pouvoir relire le diff généré avant de le valider.

Intégrer PHPCS dans le flux de travail quotidien

Un ruleset qui n’est vérifié qu’au moment du déploiement arrive toujours trop tard. Les options les plus efficaces :

• Un hook Git pre-commit qui lance phpcs sur les fichiers modifiés uniquement, pour garder un retour rapide.
• Une extension d’éditeur (PHP CodeSniffer côté Sublime Text, VS Code ou PhpStorm) qui affiche les erreurs directement pendant l’écriture du code.
• Une étape dédiée dans la CI qui échoue le build si des erreurs sont détectées, en complément du pre-commit qui reste contournable avec --no-verify.

Sur nos projets d’agence, nous évitons d’imposer WordPress-Core tel quel : ses règles de style sont pensées pour le cœur de WordPress, pas pour un plugin client. Nous préférons partir de WordPress-Extra et ajuster au cas par cas, ce qui évite des débats sans fin sur des détails d’indentation.

En résumé

PHPCS avec les WordPress Coding Standards transforme la relecture de code en un contrôle automatique, reproductible et objectif. Un phpcs.xml.dist bien construit, combiné à une intégration en pre-commit et en CI, évite la plupart des discussions stériles sur le style et laisse les revues de code se concentrer sur ce qui compte vraiment : la logique et l’architecture. La prochaine étape naturelle consiste à ajouter une couche d’analyse statique, avec un outil comme PHPStan, pour détecter des bugs que le style seul ne révèle pas.