Configurer les WordPress Coding Standards dans VS Code et PhpStorm

Pour appliquer les WordPress Coding Standards dans VS Code ou PhpStorm, on installe le paquet WPCS avec Composer (il apporte PHP_CodeSniffer, donc les commandes phpcs et phpcbf), on décrit les règles du projet dans un fichier phpcs.xml.dist, puis on branche l’éditeur sur vendor/bin/phpcs. Les erreurs s’affichent directement dans l’éditeur, et phpcbf corrige la mise en forme à l’enregistrement.

Ce guide détaille chaque étape avec des commandes testées en octobre 2026, y compris le piège de version qui fait échouer la plupart des anciens tutoriels. Je développe mes extensions et mes thèmes selon ces standards, et cet outillage repère les oublis d’échappement, de préfixe ou de traduction avant la mise en production.

Les WordPress Coding Standards, c’est quoi ?

Ce sont les règles d’écriture du code publiées par le projet WordPress dans le Coding Standards Handbook : PHP, HTML, CSS, JavaScript, accessibilité et documentation du code.

Ce que couvrent les standards PHP

Les standards PHP de WordPress mélangent deux familles de règles :

• le style : tabulations, espaces dans les parenthèses, guillemets simples, conditions « Yoda » (if ( 'publish' === $status )), noms en minuscules avec tirets bas ;
• l’interopérabilité et la sécurité : préfixer ce qui est global, échapper chaque sortie, nettoyer chaque entrée, vérifier les nonces, préparer les requêtes SQL, utiliser le bon domaine de traduction.

Même si vous préférez un autre style, le handbook recommande de suivre au moins les règles d’interopérabilité, de traduction et de sécurité.

Pourquoi les vérifier automatiquement

Personne ne retient des centaines de règles. Un outil qui les vérifie à chaque enregistrement simplifie les relectures, garde un code homogène quand quelqu’un d’autre reprend le projet, et signale tôt les failles évidentes : sortie non échappée, entrée non nettoyée, formulaire sans nonce.

Le répertoire officiel n’exige pas le style WPCS en tant que tel. En revanche, depuis octobre 2024, Plugin Check est exécuté sur chaque nouvelle extension soumise et peut bloquer l’envoi : il reprend une partie des règles de WPCS, surtout celles de sécurité.

WPCS, PHP_CodeSniffer, PHPCBF : qui fait quoi ?

PHP_CodeSniffer : phpcs détecte, phpcbf corrige

PHP_CodeSniffer (PHPCS) est le moteur. phpcs liste les écarts par rapport à un standard ; phpcbf (PHP Code Beautifier and Fixer) corrige ceux qui peuvent l’être sans risque : espaces, indentation, guillemets. PHPCBF fait donc partie de PHP_CodeSniffer. Depuis la version 3.8.0 (décembre 2023), le projet est maintenu par l’organisation PHPCSStandards, mais le paquet Composer garde son nom historique, squizlabs/php_codesniffer.

WPCS : les règles WordPress pour PHP_CodeSniffer

WordPress Coding Standards (WPCS) fournit les règles (les « sniffs ») que PHP_CodeSniffer charge, regroupées en quatre standards :

Peu de guides le signalent : WordPress-Core ne vérifie pas l’échappement, et WordPress-Extra ne vérifie pas le nettoyage des entrées. La commande phpcs -e --standard=WordPress-Extra, qui liste les règles d’un standard, le confirme : seul le standard complet WordPress contrôle qu’un $_GET['name'] passe par wp_unslash() puis par une fonction de nettoyage. Je le recommande pour tout code neuf, extension ou thème WordPress développé sur mesure. Pour reprendre le code d’un autre développeur, mieux vaut commencer par WordPress-Core, qui donne un rapport exploitable, puis durcir les règles étape par étape.

PHP CS Fixer : un autre outil, à ne pas confondre

PHP CS Fixer (FriendsOfPHP) est un correcteur de style indépendant, sans jeu de règles WordPress officiel : des réglages comme @WordPress ou @WordPress-VIP, qui circulent encore, ne correspondent à rien. Pour WPCS, phpcbf remplit déjà ce rôle.

Installer WPCS avec Composer

Depuis WPCS 3.0, Composer est la seule méthode d’installation prise en charge : on ne clone plus le dépôt et on ne règle plus installed_paths à la main.

Prérequis

• PHP 7.2 ou plus en ligne de commande, avec les extensions tokenizer, xmlwriter, simplexml, filter, libxml et xmlreader (iconv et mbstring conseillées). Sous Debian ou Ubuntu, les paquets php-xml et php-mbstring couvrent l’essentiel.
• Composer à jour (la clé allow-plugins existe depuis Composer 2.2).

Installation dans le projet (recommandée)

# À lancer à la racine de l'extension ou du thème
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev wp-coding-standards/wpcs:"^3.4.1"

# Vérifier l'installation
vendor/bin/phpcs --version
vendor/bin/phpcs -i

La première ligne autorise le plugin Composer dealerdirect/phpcodesniffer-composer-installer, qui enregistre les standards auprès de PHP_CodeSniffer. La seconde installe WPCS avec PHP_CodeSniffer 3.x, PHPCSUtils et PHPCSExtra. phpcs -i doit lister WordPress, WordPress-Core, WordPress-Docs et WordPress-Extra. Les versions étant figées dans composer.lock, l’équipe, l’éditeur et l’intégration continue appliquent exactement les mêmes règles.

Installation globale (plusieurs projets)

composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require --dev wp-coding-standards/wpcs:"^3.4.1"

# Dossier des exécutables globaux, à ajouter au PATH
composer global config bin-dir --absolute

La dernière commande affiche le dossier des exécutables : souvent ~/.config/composer/vendor/bin ou ~/.composer/vendor/bin sous Linux et macOS, %APPDATA%\Composer\vendor\bin sous Windows (fichiers phpcs.bat et phpcbf.bat). Ajoutez-le à votre PATH.

Le piège de PHP_CodeSniffer 4

Beaucoup de tutoriels (dont la première version de cet article) commencent par composer global require "squizlabs/php_codesniffer=*". Depuis septembre 2025, cette commande installe PHP_CodeSniffer 4, alors que WPCS 3.4.1 exige PHP_CodeSniffer 3 (contrainte ^3.13.5) : Composer refuse ensuite d’installer WPCS, et le standard WordPress n’apparaît jamais. Le blocage se reproduit toujours en octobre 2026 avec PHP_CodeSniffer 4.0.4. La solution : si la 4.x est déjà là, retirez-la (composer remove squizlabs/php_codesniffer), puis n’installez que WPCS, qui tire la bonne version.

Visez aussi WPCS 3.4.1 au minimum. Cette version de juillet 2026 corrige une faille de sécurité : avec les standards WordPress ou WordPress-Extra, analyser un code malveillant pouvait exécuter des commandes sur votre machine. La règle en cause contrôle les paramètres de wp_enqueue_script(), ceux qui servent à charger scripts et styles correctement. Pour mettre à jour : composer update wp-coding-standards/wpcs --with-dependencies.

Configurer les règles du projet avec phpcs.xml.dist

Plutôt que de répéter les options à chaque commande, on les écrit dans un fichier de règles (« ruleset »). PHP_CodeSniffer cherche automatiquement .phpcs.xml, phpcs.xml, .phpcs.xml.dist et phpcs.xml.dist dans le dossier courant et ses parents.

Un fichier de départ commenté

Ce fichier a été testé tel quel avec WPCS 3.4.1, PHP_CodeSniffer 3.13.6 et PHPCompatibilityWP 2.1.8 :

<?xml version="1.0"?>
<ruleset name="Mon extension">
	<description>Règles WordPress du projet.</description>

	<!-- Fichiers analysés et exclusions -->
	<file>.</file>
	<exclude-pattern>/vendor/*</exclude-pattern>
	<exclude-pattern>/node_modules/*</exclude-pattern>
	<exclude-pattern>/build/*</exclude-pattern>

	<!-- Options de la ligne de commande -->
	<arg name="extensions" value="php"/>
	<arg name="basepath" value="."/>
	<arg name="parallel" value="8"/>
	<arg value="ps"/>

	<!-- Standard WordPress complet : Core, Docs, Extra et contrôle des entrées -->
	<rule ref="WordPress"/>

	<!-- Version minimale de WordPress prise en charge par le projet -->
	<config name="minimum_wp_version" value="7.0"/>

	<!-- Domaine de traduction -->
	<rule ref="WordPress.WP.I18n">
		<properties>
			<property name="text_domain" type="array">
				<element value="mon-extension"/>
			</property>
		</properties>
	</rule>

	<!-- Préfixe des fonctions, classes, constantes et hooks -->
	<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
		<properties>
			<property name="prefixes" type="array">
				<element value="monext"/>
			</property>
		</properties>
	</rule>

	<!-- Compatibilité PHP (paquet phpcompatibility/phpcompatibility-wp) -->
	<config name="testVersion" value="7.4-"/>
	<rule ref="PHPCompatibilityWP">
		<include-pattern>*\.php$</include-pattern>
	</rule>
</ruleset>

Le suffixe .dist désigne le fichier partagé, versionné dans Git ; un phpcs.xml local, ignoré par Git, peut le remplacer sur un poste. L’argument ps affiche la progression et le nom de chaque règle en infraction.

Préfixes, domaine de traduction et version minimale de WordPress

• prefixes : le préfixe de vos fonctions, classes, constantes et hooks. Tout ce qui n’en a pas est signalé, ce qui évite les collisions avec les autres extensions.
• text_domain : le domaine attendu dans __(), esc_html__() et les autres fonctions de traduction. Une faute de frappe rend un texte intraduisible sans erreur visible.
• minimum_wp_version : la plus ancienne version de WordPress prise en charge (celle de l’en-tête Requires at least), pour signaler les fonctions dépréciées. Par défaut, WPCS 3.4 utilise 6.7.

Les autres propriétés réglables sont listées dans le wiki de WPCS : Customizable sniff properties.

Exclure une règle

Le nom complet de la règle s’affiche entre parenthèses dans le rapport (option -s, incluse dans ps). Placez l’exclusion dans la balise rule du standard. Exemple courant : un projet qui charge ses classes en PSR-4 ne peut pas suivre la convention de nommage des fichiers de WordPress.

<rule ref="WordPress">
	<!-- Classes chargées en PSR-4 : noms de fichiers libres -->
	<exclude name="WordPress.Files.FileName"/>
</rule>

Vérifier la compatibilité PHP avec PHPCompatibilityWP

Le bloc testVersion signale le code incompatible avec une version de PHP que vous prenez en charge. Il demande un paquet de plus, dans sa branche stable 2.1 (la 3.0 est encore en alpha) : composer require --dev phpcompatibility/phpcompatibility-wp:"^2.1". Sans ce paquet, supprimez le bloc, sinon PHP_CodeSniffer s’arrête sur un standard introuvable.

7.4- signifie « PHP 7.4 et suivants » : c’est le minimum de WordPress depuis la version 7.0, qui a abandonné PHP 7.2 et 7.3 (la version recommandée reste PHP 8.3 ou plus). Si votre extension exige PHP 8.1, écrivez 8.1-. Gardez ce réglage cohérent avec minimum_wp_version : une extension qui prend encore en charge WordPress 6.x doit tester à partir de PHP 7.2 (7.2-).

Lancer phpcs et phpcbf en ligne de commande

Vérifiez d’abord que tout fonctionne dans le terminal : c’est là que les messages d’erreur sont les plus clairs.

Lire le rapport de phpcs

Prenons un fichier volontairement fautif, typique d’un premier essai d’extension :

<?php
/**
 * Plugin Name: Mon extension
 */
function bonjour(){
  $name = $_GET['name'];
  echo "<p>Bonjour " . $name . "</p>";
  _e( 'Merci de votre visite', 'autre-domaine' );
}
add_action('wp_footer','bonjour');

Extrait du rapport obtenu avec le fichier de règles ci-dessus (21 problèmes en tout) :

FILE: src/demo.php
--------------------------------------------------------------------------------
FOUND 17 ERRORS AND 4 WARNINGS AFFECTING 6 LINES
--------------------------------------------------------------------------------
  5 | ERROR   | [ ] Functions declared in the global namespace by a
    |         |     theme/plugin should start with the theme/plugin prefix.
    |         |     Found: "bonjour".
    |         |     (WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound)
  5 | ERROR   | [x] Expected 1 space before opening brace; found 0
    |         |     (Generic.Functions.OpeningFunctionBraceKernighanRitchie.SpaceBeforeBrace)
  6 | ERROR   | [ ] Detected usage of a non-sanitized input variable:
    |         |     $_GET['name']
    |         |     (WordPress.Security.ValidatedSanitizedInput.InputNotSanitized)
  7 | ERROR   | [ ] All output should be run through an escaping function (see
    |         |     the Security sections in the WordPress Developer
    |         |     Handbooks), found '$name'.
    |         |     (WordPress.Security.EscapeOutput.OutputNotEscaped)
(…)
PHPCBF CAN FIX THE 12 MARKED SNIFF VIOLATIONS AUTOMATICALLY

La case [x] signale une correction automatique possible, [ ] un problème à corriger vous-même. Tant qu’il reste des erreurs, la commande renvoie un code de retour non nul : c’est ce qui fera échouer une intégration continue.

Corriger automatiquement avec phpcbf

vendor/bin/phpcbf src/demo.php corrige ici 12 problèmes : indentation, espaces, guillemets. Il en reste 9, les plus importants : préfixe manquant, entrée non nettoyée, sortie non échappée, mauvais domaine de traduction, nonce. phpcbf corrige la forme, jamais la sécurité. Voici la version qui passe sans aucune erreur :

<?php
/**
 * Plugin Name: Mon extension
 * Text Domain: mon-extension
 *
 * @package MonExtension
 */

defined( 'ABSPATH' ) || exit;

/**
 * Affiche un message de bienvenue dans le pied de page.
 *
 * @return void
 */
function monext_bonjour() {
	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Lecture seule, aucune donnée modifiée.
	$name = isset( $_GET['name'] ) ? sanitize_text_field( wp_unslash( $_GET['name'] ) ) : '';

	/* translators: %s: nom du visiteur. */
	$message = sprintf( __( 'Bonjour %s', 'mon-extension' ), $name );

	echo '<p>' . esc_html( $message ) . '</p>';
	echo '<p>' . esc_html__( 'Merci de votre visite', 'mon-extension' ) . '</p>';
}
add_action( 'wp_footer', 'monext_bonjour' );

Le phpcs:ignore est volontaire : la page affiche un paramètre d’URL sans rien enregistrer, un nonce n’apporterait rien. Un formulaire qui modifie des données doit en revanche toujours vérifier un nonce et les droits de l’utilisateur. Pour aller plus loin dans la création d’extensions, voyez mon article pour se former au développement de plugins WordPress.

Ignorer une règle de façon justifiée

Quand une règle ne s’applique pas, par exemple à une requête sur une table créée par votre extension, désactivez-la sur la ligne suivante seulement, en la nommant et en donnant la raison après -- :

<?php
/**
 * Compte les entrées du journal d'un utilisateur (table personnalisée).
 *
 * @param int $user_id Identifiant de l'utilisateur.
 * @return int
 */
function monext_count_logs( $user_id ) {
	global $wpdb;

	// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table personnalisée, compteur en temps réel.
	return (int) $wpdb->get_var(
		$wpdb->prepare( "SELECT COUNT(*) FROM {$wpdb->prefix}monext_logs WHERE user_id = %d", $user_id )
	);
}

Pour un bloc, encadrez-le de // phpcs:disable Nom.De.La.Regle et // phpcs:enable Nom.De.La.Regle. Évitez phpcs:ignoreFile et les phpcs:disable sans nom de règle : ils masquent aussi les problèmes futurs.

Ajouter des scripts Composer

{
	"scripts": {
		"lint:php": "phpcs --standard=phpcs.xml.dist",
		"fix:php": "phpcbf --standard=phpcs.xml.dist"
	}
}

Composer ajoute vendor/bin au PATH de ses scripts : composer lint:php analyse, composer fix:php corrige (quand phpcbf a modifié un fichier, Composer signale un code de retour 1 : c’est normal). Le --standard explicite sert surtout à PhpStorm, qui le lit pour choisir votre fichier de règles.

Configurer VS Code pour les WordPress Coding Standards

VS Code a besoin d’une extension qui appelle phpcs et phpcbf. Une seule à la fois, sinon les erreurs apparaissent en double et les formateurs se contredisent.

Quelle extension choisir ?

Deux extensions sont maintenues (vérifié sur le Marketplace en octobre 2026) :

• PHP Sniffer & Beautifier (ValeryanM.vscode-phpsab) : analyse et correction, détection automatique de Composer et du fichier de règles. Elle ne prend pas en charge PHP_CodeSniffer 4.
• PHP_CodeSniffer (obliviousharmony.vscode-php-codesniffer) : analyse et formatage. Elle ne fait rien tant qu’aucun standard n’est choisi (valeur Disabled par défaut).

À éviter : l’extension « phpcs » d’ikappas, citée par de nombreux anciens tutoriels, n’est plus mise à jour depuis 2018. Et PHP Intelephense, excellente pour l’autocomplétion, n’exécute pas PHPCS : le réglage intelephense.environment.phpcs.standard n’existe pas.

Réglages avec PHP Sniffer & Beautifier

Avec WPCS installé dans le projet (composer.json et composer.lock à la racine de l’espace de travail) et un phpcs.xml.dist, l’extension trouve seule les exécutables et les règles. Dans .vscode/settings.json :

{
	"phpsab.snifferEnable": true,
	"phpsab.snifferMode": "onType",
	"phpsab.snifferShowSources": true,
	"phpsab.fixerEnable": true,
	"[php]": {
		"editor.defaultFormatter": "ValeryanM.vscode-phpsab",
		"editor.formatOnSave": true
	}
}

onType analyse pendant la frappe (par défaut : à l’enregistrement) ; snifferShowSources affiche le nom de la règle. Le bloc [php] fait de phpcbf le formateur des fichiers PHP, appliqué à chaque enregistrement.

Réglages avec l’extension PHP_CodeSniffer

{
	"phpCodeSniffer.standard": "Automatic",
	"phpCodeSniffer.autoExecutable": true,
	"[php]": {
		"editor.defaultFormatter": "obliviousharmony.vscode-php-codesniffer",
		"editor.formatOnSave": true
	}
}

Automatic cherche le fichier de règles du dossier du fichier ouvert jusqu’à la racine de l’espace de travail ; autoExecutable utilise le phpcs du dossier vendor.

Avec une installation globale

Indiquez le standard et, si besoin, le chemin des exécutables, de préférence dans vos paramètres utilisateur (« Preferences: Open User Settings (JSON) »). Sous Windows, visez les fichiers .bat ; les barres obliques fonctionnent :

{
	"phpsab.standard": "WordPress",
	"phpsab.executablePathCS": "C:/Users/votre-nom/AppData/Roaming/Composer/vendor/bin/phpcs.bat",
	"phpsab.executablePathCBF": "C:/Users/votre-nom/AppData/Roaming/Composer/vendor/bin/phpcbf.bat"
}

Configurer PhpStorm avec PHPCS et WPCS

PhpStorm intègre PHP_CodeSniffer sans extension. Les chemins suivent la documentation de PhpStorm 2026.2 ; les réglages s’ouvrent avec Ctrl+Alt+S (sous macOS : PhpStorm > Settings).

Déclarer PHP_CodeSniffer et PHPCBF

1. Installez WPCS dans le projet avec Composer. PhpStorm détecte alors vendor/bin/phpcs et vendor/bin/phpcbf, et sélectionne le standard WordPress quand wp-coding-standards/wpcs figure dans require-dev.
2. Vérifiez dans Settings > PHP > Quality Tools > PHP_CodeSniffer. Si le champ Configuration est vide (installation globale), ouvrez le dialogue à côté de la liste et renseignez les chemins de phpcs et phpcbf (.bat sous Windows).
3. Pour appliquer votre phpcs.xml.dist, choisissez le standard Custom dans les options de l’outil et indiquez le chemin du fichier. Le script Composer vu plus haut permet à PhpStorm de le faire automatiquement.

Après une modification de composer.json, réinitialisez la configuration sur la page Quality Tools puis mettez à jour les dépendances : PhpStorm ne la relit pas de lui-même.

Activer l’inspection PHP_CodeSniffer validation

Dans Settings > Editor > Inspections, dépliez PHP > Quality Tools et cochez PHP_CodeSniffer validation. Les problèmes sont soulignés dans l’éditeur avec le préfixe phpcs. Pour tout le projet : Code > Inspect Code.

Corriger avec PHPCBF

Sur une erreur, Alt+Entrée propose PHP Code Beautifier and Fixer: fix the whole file. Pour passer par le raccourci de mise en forme, déclarez PHPCBF dans Settings > PHP > Quality Tools, section External formatters : Code > Reformat Code (Ctrl+Alt+L) l’utilise alors, y compris à l’enregistrement et avant un commit.

Appliquer le style de code WordPress

Pour que le formateur intégré de PhpStorm (indentation pendant la frappe, Reformat Code sans PHPCBF) suive les mêmes règles que phpcbf : Settings > Editor > Code Style > PHP, Set from…, puis Predefined Style > WordPress. PhpStorm propose aussi ce style de code WordPress à l’activation de son intégration WordPress.

Aller plus loin : Plugin Check et intégration continue

• Plugin Check, l’extension officielle de l’équipe du répertoire, s’utilise dans Outils > Plugin Check ou avec WP-CLI (wp plugin check mon-extension). Elle vérifie aussi ce que PHPCS ne voit pas : en-têtes, fichier readme, règles du répertoire. Lancez-la avant toute soumission.
• L’intégration continue : faites tourner composer lint:php sur chaque demande de fusion ; le wiki de WPCS décrit la configuration pour GitHub Actions. En local, phpcs --filter=GitStaged n’analyse que les fichiers indexés, pratique avant un commit.

PHPCS vérifie la forme et la sécurité ligne par ligne, pas l’architecture : pour cela, voyez les principes SOLID appliqués à WordPress. Et si vous adaptez une extension existante, analysez aussi l’extension compagnon qui porte vos modifications : c’est la méthode que je décris pour personnaliser un plugin WordPress sans le modifier.

Questions fréquentes sur PHPCS et les WordPress Coding Standards

En résumé

1. Installez WPCS (3.4.1 ou plus) avec Composer dans le projet : il apporte PHP_CodeSniffer 3, phpcs et phpcbf.
2. Décrivez vos règles dans phpcs.xml.dist : standard WordPress complet, préfixes, domaine de traduction, versions minimales de WordPress et de PHP.
3. Branchez l’éditeur : PHP Sniffer & Beautifier ou PHP_CodeSniffer dans VS Code, Quality Tools et Inspections dans PhpStorm.
4. Laissez phpcbf corriger la forme, et corrigez vous-même l’échappement, le nettoyage des entrées et les nonces.

Vous préférez confier le développement de votre extension ? Je réalise des extensions WordPress sur mesure selon ces mêmes standards. Pour en parler, contactez-moi.

Mis à jour en octobre 2026 par un développeur WordPress freelance senior.