Vous écrivez du code pour WordPress et votre collègue vous demande systématiquement de «nettoyer les espaces et l’indentation» à chaque revue de code? Ou votre site plante après une mise à jour de plugin et vous ne trouvez pas l’erreur dans les logs parce que le code a été écrit sans aucune norme cohérente?

C’est un scénario familier pour toute personne qui développe pour WordPress en équipe. Des habitudes de formatage différentes, certains utilisent les conditions Yoda et d’autres non, et il manque de l’échappement de sortie par endroits.

PHP CodeSniffer règle cela automatiquement: il vérifie votre code par rapport aux normes de codage WordPress directement dans votre éditeur, signale les violations et peut les corriger avec une seule commande. Voici un guide de configuration à partir de zéro pour PhpStorm 2026.

💡 Aperçu rapide:

• Installez PHP CodeSniffer et les normes de codage WordPress via Composer, dans votre projet ou globalement
• Définissez le chemin vers phpcs dans la configuration et ajoutez la norme WordPress
• Configurez un interpréteur PHP distant si vous travaillez via Vagrant, Docker ou SSH
• Activez l’inspection PHP CodeSniffer Validation dans PhpStorm, et les erreurs seront signalées à la volée
• Mettez en place le formatage automatique avec PHP Code Beautifier and Fixer pour corriger le code avec une seule commande

Vidéo pas à pas en anglais (mêmes étapes que dans le texte):

Étape 1: configurer un interpréteur PHP distant

Si vous développez avec un PHP local (XAMPP, MAMP, Local, serveur intégré), passez cette étape. Pour Vagrant, Docker ou un serveur distant via SSH, vous devez spécifier l’interpréteur explicitement.

Ouvrez Settings → PHP (Ctrl+Alt+S), cliquez sur […] à côté de CLI Interpreter et sélectionnez SSH Credentials ou Docker Compose.

Remplissez:

• Adresse IP de l’hôte, la même que celle utilisée pour le site (ping example.dev vous aidera)
• vagrant pour le nom d’utilisateur et le mot de passe (si vous utilisez Vagrant)
• /usr/bin/php, chemin vers l’exécutable PHP sur le serveur

Enregistrez et sélectionnez l’interpréteur créé dans la liste:

PhpStorm utilisera ce PHP spécifique pour exécuter CodeSniffer et d’autres outils de qualité de code.

Étape 2: installer PHP CodeSniffer via Composer

L’approche la plus fiable consiste à installer PHPCS comme dépendance de projet. Ajoutez à votre composer.json:

1
{
2
  "require-dev": {
3
    "squizlabs/php_codesniffer": "^3.10"
4
  }
5
}

Puis lancez composer install. PhpStorm détectera automatiquement phpcs et phpcbf dans vendor/bin, vous n’aurez donc pas besoin de définir les chemins manuellement.

Pour une installation globale (si vous en avez besoin sur tous les projets):

1
composer global require "squizlabs/php_codesniffer=*"

Vérifiez: l’exécutable phpcs doit se trouver dans ~/.composer/vendor/bin/ (Linux/Mac) ou %APPDATA%/Composer/vendor/bin/ (Windows).

Étape 3: installer les WordPress Coding Standards

WPCS est un ensemble de règles (sniffs) pour PHPCS qui vérifie la conformité spécifique aux standards WordPress: échappement des sorties, conditions Yoda, préfixes de fonctions, et tout le reste du manuel des standards de codage WordPress.

Via Composer dans votre projet:

1
composer require --dev wp-coding-standards/wpcs:"^3.0"

Ou globalement (l’ancienne méthode éprouvée):

1
composer create-project wp-coding-standards/wpcs:dev-master --no-dev

Assurez-vous que le standard apparaît dans ~/.composer/wpcs/ ou vendor/wp-coding-standards/wpcs/.

Étape 4: définir le chemin du standard dans la configuration de PHPCS

Naviguez jusqu’au dossier phpcs et indiquez où se trouvent les standards installés:

1
cd ~/.composer/vendor/bin
2
phpcs --config-set installed_paths ~/.composer/wpcs

Vérifiez que WordPress apparaît dans la liste des standards disponibles:

1
phpcs -i

La sortie doit afficher quatre standards: WordPress, WordPress-Core, WordPress-Docs et WordPress-Extra.

Étape 5: ajouter phpcs au PATH

Ouvrez ~/.bash_profile (ou ~/.zshrc pour ZSH) et ajoutez la ligne:

1
PATH=$PATH:~/.composer/vendor/bin

Redémarrez votre terminal ou exécutez source ~/.bash_profile. La commande phpcs est désormais disponible depuis n’importe quel dossier.

Testez-la sur n’importe quel fichier de thème ou d’extension:

1
cd wp-content/themes/your-theme
2
phpcs --standard=WordPress functions.php

Une sortie réussie ressemble à ceci:

Les erreurs sont réparties en deux niveaux: ERROR pour les violations strictes et WARNING pour les recommandations. Chaque ligne contient le numéro de la règle et une description du problème.

Étape 6: configurer PHP CodeSniffer dans PhpStorm

Ouvrez Settings → PHP → Quality Tools → PHP_CodeSniffer (Ctrl+Alt+S).

Si vous avez installé via Composer dans votre projet, PhpStorm détectera automatiquement phpcs depuis vendor/bin. En cas d’installation globale, cliquez sur […] à côté de Configuration et indiquez le chemin de l’exécutable: ~/.composer/vendor/bin/phpcs.

Sélectionnez l’interpréteur PHP dans la liste, le même que celui configuré à l’étape 1.

Étape 7: activer l’inspection PHP CodeSniffer Validation

Allez dans Settings → Editor → Inspections, déroulez PHP → Quality Tools et cochez PHP_CodeSniffer validation.

Dans la liste déroulante Coding standard, sélectionnez WordPress. Enregistrez les paramètres.

À partir de maintenant, PhpStorm vérifie les fichiers PHP ouverts en temps réel. Les violations sont soulignées en vaguelettes, comme les erreurs classiques de l'IDE. Survolez-les et une infobulle apparaît avec une description: ce qui ne va pas et comment le corriger.

Étape 8: vérifier que tout fonctionne

Créez ou ouvrez n'importe quel fichier PHP de thème et écrivez volontairement du code non conforme:

1
if(true){echo 'Spaces? Never heard of them';}

PhpStorm soulignera la ligne: espaces manquants après if, autour des accolades et à l'intérieur de la condition. Survolez avec le curseur et vous verrez le texte de l'erreur ainsi que le numéro de la règle WordPress.

Étape 9: configurer la correction automatique via PHP Code Beautifier and Fixer

Vous n'avez pas à corriger chaque violation manuellement. PHP Code Beautifier and Fixer (phpcbf) est installé avec PHPCS et peut corriger automatiquement le code selon le standard choisi.

Ouvrez Settings → PHP → Quality Tools, dans la section External Formatters, sélectionnez PHP Code Beautifier and Fixer. Désormais, lorsque vous lancez Code → Reformat Code (Ctrl+Alt+L / Cmd+Option+L), PhpStorm ne se contente pas d'aligner l'indentation avec son propre formateur, il applique aussi les règles WordPress via phpcbf.

Par ailleurs, configurez le style de code WordPress pour le formateur intégré: Settings → Editor → Code Style → PHP → Set From → Predefined Style → WordPress. Ainsi, les deux outils travaillent dans le même sens et n'entrent pas en conflit.

Étape 10: que faire pour les nouveaux projets

Pour chaque nouveau projet WordPress, répétez simplement l'étape 1 (interpréteur, s'il est distant), l'étape 6 (définir phpcs dans les paramètres) et l'étape 7 (activer l'inspection). Si vous utilisez Composer dans votre projet, les étapes 2 à 4 sont couvertes par une seule ligne: composer require --dev wp-coding-standards/wpcs.

⁉️🤔 Foire aux questions

Quelle est la différence entre WordPress, WordPress-Core, WordPress-Docs et WordPress-Extra?

WordPress est l'ensemble de base de toutes les règles, sauf celles de documentation. WordPress-Core contient uniquement les règles du guide de codage officiel (indentation, nommage, conditions Yoda). WordPress-Extra ajoute des contrôles de sécurité: échappement de sortie, validation des données d'entrée. WordPress-Docs vérifie les standards de documentation du code (PHPDoc). En pratique, utilisez WordPress, car il inclut Core et Extra.

PhpStorm ne voit pas phpcs après l'installation. Que faire?

Vérifiez que le dossier vendor/bin (ou ~/.composer/vendor/bin) est bien dans le PATH et qu'il contient l'exécutable phpcs. Dans PhpStorm, ouvrez Settings → PHP → Quality Tools → PHP_CodeSniffer, cliquez sur […] et indiquez manuellement le chemin vers phpcs. Après un changement d'interpréteur ou une réinstallation des dépendances, il peut être nécessaire de réinitialiser la configuration via le bouton Reset dans la même fenêtre.

Puis-je utiliser PHPCS sans Composer, en téléchargeant simplement l'archive phar?

Oui, mais nous ne le recommandons pas. Avec une installation via Composer, PhpStorm détecte automatiquement phpcs, phpcbf et tous les standards enregistrés. Avec l'archive phar, vous devrez configurer les chemins manuellement et gérer les mises à jour séparément. Pour le travail en équipe, une dépendance Composer dans composer.json verrouille la version, ce qui garantit que tous les développeurs utilisent le même ensemble de règles.

Comment exclure des fichiers ou dossiers spécifiques de la vérification?

Créez un fichier phpcs.xml à la racine de votre projet. Vous pouvez y exclure des répertoires (<exclude-pattern>vendor/*</exclude-pattern>), définir le standard et modifier la sévérité de règles individuelles. PhpStorm détectera automatiquement ce fichier s'il se trouve à la racine du projet et se nomme phpcs.xml ou phpcs.xml.dist.

Pourquoi PHPCS signale-t-il une erreur sur wp_redirect() sans exit?

Le standard WordPress exige exit ou wp_die() après toute redirection: wp_redirect() ne fait que définir l'en-tête, mais n'arrête pas l'exécution du script. Sans exit, le code situé après la redirection continue de s'exécuter, ce qui constitue une faille de sécurité. L'usage correct est: wp_redirect( home_url() ); exit;.

Que faire si votre base de code est déjà volumineuse et que vous commencez tout juste à mettre en place des standards

Lancer PHPCS sur un projet qui compte des milliers de violations est le meilleur moyen de démotiver votre équipe. Commencez modestement: corrigez les erreurs critiques (error, pas warning) avec phpcbf, puis abaissez progressivement le seuil. Ajoutez un phpcs.xml avec des exclusions pour le code legacy et activez de nouvelles règles une par une, chaque mois.

Voici un plan étape par étape pour mettre en place des standards sur un projet en production:

• Lancez phpcs --standard=WordPress --report=summary pour voir le nombre total d'erreurs.
• Corrigez automatiquement tout ce qui peut l'être: phpcbf --standard=WordPress .
• Triez les erreurs restantes par sévérité, en traitant d'abord les plus critiques.
• Ajoutez la vérification dans la CI (GitHub Actions, GitLab CI): faites en sorte que le build échoue en cas de nouvelles violations dans les pull requests.

Commencez par un simple composer require --dev wp-coding-standards/wpcs sur un projet. Au bout d'une semaine, l'équipe se sera habituée à la coloration syntaxique. Au bout d'un mois, elle sera habituée au code propre. Quel standard de codage utilisez-vous? Dites-le-nous dans les commentaires.