# PHPCS et PHPStan dans la même CI : lequel bloquer, lequel doit seulement avertir

> Les deux outils tournent souvent côte à côte en CI, mais leurs erreurs ne méritent pas le même traitement. Un comparatif pour décider quel seuil bloque réellement une fusion.

- Auteur : Clément Hadrot
- Publié le : 2025-05-15
- Mis à jour le : 2025-05-15
- Catégorie : Tests
- URL : https://wpmoderne.dev.wordpress-developpement.fr/tests/phpcs-phpstan-meme-ci-bloquant-avertissement/

## L’essentiel

- PHPCS et PHPStan ne détectent pas le même type de risque, malgré leur ressemblance en CI
- Bloquer la fusion sur tout avertissement produit une fatigue qui pousse à ignorer l'outil
- Un niveau de sévérité différencié garde chaque outil utile sans paralyser l'équipe

PHPCS et PHPStan cohabitent dans la plupart des pipelines WordPress modernes, souvent installés le même jour et configurés avec la même exigence stricte : tout signalement bloque la fusion de la pull request. Cette symétrie de traitement masque une différence de nature entre les deux outils, qui finit par coûter cher en frustration d'équipe si elle n'est jamais interrogée.

PHPCS vérifie une conformité à un standard de style, essentiellement cosmétique : indentation, espacement, ordre des déclarations. PHPStan, lui, analyse la cohérence des types et repère des erreurs qui provoqueraient réellement un plantage à l'exécution. Traiter ces deux catégories d'erreurs avec la même sévérité de blocage revient à donner autant de poids à un espace mal placé qu'à un appel de méthode sur une valeur potentiellement nulle.

## Ce que chaque outil détecte, en pratique

| Type d'erreur | PHPCS | PHPStan |
| --- | --- | --- |
| Indentation incorrecte | Détecté | Ignoré |
| Appel de méthode sur objet potentiellement null | Ignoré | Détecté |
| Espace manquant après une virgule | Détecté | Ignoré |
| Paramètre de type incompatible avec la signature | Ignoré | Détecté |
| Fonction WordPress dépréciée utilisée | Détecté (via WPCS) | Partiel, selon les stubs installés |

## Le critère retenu pour arbitrer la sévérité

> L'essentiel à retenir : PHPCS et PHPStan ne détectent pas le même type de risque, malgré leur ressemblance en CI ; Bloquer la fusion sur tout avertissement produit une fatigue qui pousse à ignorer l'outil ; Un niveau de sévérité différencié garde chaque outil utile sans paralyser l'équipe

La question posée pour chaque catégorie d'erreur n'était pas « l'outil a-t-il raison ? », mais « cette erreur peut-elle casser le site en production si elle passe inaperçue ? ». Trois niveaux de sévérité en ont découlé, appliqués indépendamment à chaque outil selon la nature de ses règles.

```
# .github/workflows/qualite.yml (extrait)
- name: PHPStan (bloquant)
  run: vendor/bin/phpstan analyse --error-format=github

- name: PHPCS règles critiques (bloquant)
  run: vendor/bin/phpcs --standard=phpcs-bloquant.xml

- name: PHPCS style (avertissement uniquement)
  run: vendor/bin/phpcs --standard=phpcs-style.xml || true
```

Le troisième job ne fait jamais échouer le pipeline grâce au `|| true`, mais son résultat reste visible dans les journaux et dans un résumé posté en commentaire de la pull request, consultable sans obliger personne à corriger avant fusion.

### Deux fichiers de configuration PHPCS, un seul standard partagé

Plutôt que de dupliquer intégralement la configuration, le fichier `phpcs-bloquant.xml` importe uniquement les règles jugées critiques du standard WordPress Coding Standards, comme la détection de fonctions dépréciées ou d'échappement de sortie manquant, tandis que `phpcs-style.xml` couvre l'ensemble du standard, y compris les règles purement esthétiques.

## Le risque d'un avertissement jamais bloquant

Reléguer une catégorie d'erreurs au simple avertissement comporte un risque symétrique : qu'elle finisse ignorée indéfiniment, faute de contrainte. La parade retenue ici consiste en une revue mensuelle du volume d'avertissements non traités, présentée en réunion d'équipe, sans bloquer aucune fusion individuelle mais en maintenant une pression collective sur la dette accumulée.

## Ce que ce découpage ne remplace pas

- Il ne remplace pas une configuration initiale soignée des deux outils, avec un niveau PHPStan adapté à la maturité réelle du projet.
- Il ne dispense pas d'ajuster la liste des règles critiques au fil du temps, à mesure que l'équipe identifie de nouveaux risques.
- Il suppose une confiance mutuelle dans l'équipe : un avertissement non bloquant reste une responsabilité, pas une permission d'ignorer.

> Un outil qui bloque tout finit par ne plus rien bloquer, parce que l'équipe apprend à le contourner plutôt qu'à l'écouter.

## Notre verdict

PHPStan mérite un traitement bloquant sur l'essentiel de ses règles, tant les erreurs qu'il détecte touchent au comportement réel du code. PHPCS gagne à être scindé en deux : un socle critique bloquant, hérité des règles de sécurité et de compatibilité WordPress, et un ensemble de règles de style traité en avertissement suivi, mais jamais en obstacle systématique à la fusion d'une pull request.