Une extension de 15 000 lignes, jamais analysée statiquement depuis sa création, générait plus de 3 000 erreurs dès le premier lancement de PHPStan au niveau 5. Corriger l’existant avant de pouvoir seulement activer l’outil en intégration continue aurait immobilisé l’équipe pendant des semaines. La baseline résout précisément ce problème : elle permet d’activer PHPStan immédiatement, en gelant les erreurs déjà présentes, tout en bloquant toute nouvelle erreur introduite à partir de maintenant.
Le principe est simple : PHPStan génère un fichier listant chaque erreur actuelle avec sa localisation exacte, puis ignore ces erreurs précises lors des analyses suivantes. Toute erreur qui n’est pas dans ce fichier de baseline fait échouer l’analyse, ce qui empêche mécaniquement la dette technique de grossir davantage, même sans la résorber immédiatement.
Générer la baseline initiale
composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse src --level 5 --generate-baseline
Cette commande crée un fichier phpstan-baseline.neon, à inclure dans la configuration principale :
# phpstan.neon
includes:
- phpstan-baseline.neon
parameters:
level: 5
paths:
- src
À partir de ce moment, vendor/bin/phpstan analyse passe au vert immédiatement, malgré les 3 000 erreurs toujours présentes dans le code — elles sont gelées, pas résolues.
Monter les niveaux progressivement
PHPStan propose des niveaux de 0 à 9 (parfois appelé max), chacun ajoutant des vérifications plus strictes que le précédent. Sauter directement au niveau 9 sur un projet non préparé génère une explosion d’erreurs difficile à trier. La bonne pratique consiste à monter d’un niveau à la fois, en régénérant la baseline à chaque palier :
vendor/bin/phpstan analyse src --level 6 --generate-baseline
vendor/bin/phpstan analyse src --level 7 --generate-baseline
Chaque montée de niveau élargit la baseline avec les nouvelles erreurs détectées à ce niveau, mais le code déjà propre au niveau précédent reste protégé contre toute régression future à ce même niveau.
Empêcher la baseline de grossir en continu
Le vrai danger d’une baseline mal surveillée est qu’un développeur pressé régénère la baseline à chaque nouvelle erreur au lieu de la corriger, ce qui vide l’outil de son intérêt. Deux garde-fous limitent ce risque :
- Interdire dans les règles de contribution la régénération de la baseline sans justification explicite en revue de code
- Suivre le nombre de lignes du fichier
phpstan-baseline.neondans le temps : une baseline qui grossit à chaque sprint signale un problème d’équipe, pas seulement un problème de code - Fixer un objectif trimestriel de réduction du nombre d’entrées dans la baseline, même modeste
La baseline n’est pas un tapis sous lequel on cache la poussière indéfiniment. C’est un point de départ honnête : elle dit exactement ce qui reste à corriger, ligne par ligne, plutôt que de prétendre que tout va bien.
Résorber la baseline module par module
Plutôt que de viser une correction massive, traiter la baseline fichier par fichier lors de tout passage dans une zone de code, même pour une autre raison, permet de la réduire organiquement. Corriger les cinq erreurs d’un fichier qu’on modifie déjà pour une fonctionnalité coûte marginalement peu, comparé à une campagne de nettoyage dédiée qui n’arrive jamais à être priorisée.
En résumé
La baseline permet d’introduire PHPStan sur un projet existant sans blocage immédiat, à condition de la traiter comme une dette à rembourser plutôt que comme une case cochée définitivement. L’installation et la configuration initiale de PHPStan pour un nouveau projet, sans historique d’erreurs à gérer, ne pose pas ce problème et ne nécessite pas cette étape.
