PHPStan : analyse statique PHP

La baseline permet d'activer PHPStan au niveau max sur une base de code existante sans corriger toutes les erreurs d'un coup : elle capture les erreurs actuelles pour ne signaler ensuite que les nouvelles.

1. Générer la baseline.

On lance l'analyse avec --generate-baseline, qui écrit le fichier phpstan-baseline.neon (liste des erreurs avec leur message, leur fichier et leur nombre d'occurrences) :

vendor/bin/phpstan analyse src tests --level=10 --memory-limit=1G -vv -c phpstan.neon --allow-empty-baseline --generate-baseline

Détail des options :

• analyse src tests : commande d'analyse, ciblée sur les dossiers src et tests.
• --level=10 : niveau de rigueur maximal, celui vers lequel on veut converger.
• --memory-limit=1G : relève la limite mémoire, l'analyse d'un gros projet au niveau max étant gourmande.
• -vv : mode verbeux, utile pour suivre la progression et diagnostiquer un éventuel plantage.
• -c phpstan.dev.neon : fichier de configuration à utiliser.
• --allow-empty-baseline : autorise l'écriture d'un fichier même quand il n'y a aucune erreur à figer.
• --generate-baseline : déclenche l'écriture de phpstan-baseline.neon au lieu d'afficher les erreurs.

Nous avons encapsulé cette commande dans une commande Make de notre standard-bundle pour en simplifier l'usage au quotidien.

Chaque entrée du fichier généré combine trois informations : le message d'erreur (transformé en expression régulière), le fichier concerné et un count :

-
    message: '#^Method App\Entity\BroadcastMessage::getContactTypes\(\) return type has no value type specified in iterable type array\.$#'
    identifier: missingType.iterableValue
    count: 1
    path: src/Entity/BroadcastMessage.php

Le count est le nombre d'occurrences figées pour ce couple message / fichier : PHPStan ne masque que ce volume exact. Si une nouvelle occurrence du même type apparaît dans le fichier, le compteur réel dépasse celui de la baseline et l'erreur est bien remontée. La baseline fige donc un état précis, elle ne neutralise pas un motif d'erreur pour toujours.

2. Inclure la baseline dans la config.

Le fichier généré se référence dans la section includes du phpstan.neon, avant les paramètres :

includes:
    - phpstan-baseline.neon
parameters:
    # ...

À partir de là, PHPStan ignore les erreurs figées et ne fait échouer la CI que sur les nouvelles régressions.

Committer le fichier. phpstan-baseline.neon doit impérativement être versionné dans le dépôt.

La CI travaille sur un checkout propre et a besoin du fichier pour savoir quelles erreurs ignorer : s'il n'est pas commité, elle ne le trouve pas, réanalyse tout et remonte à tort l'ensemble des erreurs pourtant figées dans la baseline, faisant échouer la pipeline sans raison.

3. Réduire la baseline dans le temps.

À chaque correction d'une erreur historique, on régénère la baseline puis on la commite pour verrouiller le progrès.

Pour que ce cycle reste honnête, l'option reportUnmatchedIgnoredErrors doit rester activée (true, sa valeur par défaut). Elle fait échouer l'analyse dès qu'une entrée de la baseline ne correspond plus à aucune erreur réelle, typiquement parce que l'erreur a été corrigée.

PHPStan signale ainsi les entrées devenues obsolètes et force à régénérer le fichier : sans elle, une erreur corrigée resterait figée à tort dans la baseline, qui ne se réduirait jamais et masquerait silencieusement des erreurs qui pourraient réapparaître.

parameters:
    reportUnmatchedIgnoredErrors: true

À distinguer de l'option ignoreErrors du phpstan.neon, réservée aux faux positifs ou aux erreurs qu'on assume de ne pas corriger : la baseline est un inventaire temporaire destiné à être résorbé, ignoreErrors est un choix délibéré souvent plus durable à bien documenter en commentaire dans le phpstan.neon.

Si un cas très spécifique de faux positif remonté par PHPStan intervient il est possible d'ignorer temporairement l'erreur :

Scénario local spécifique à une ligne d'un seul fichier :

Dans l'exemple suivant la méthode getNextSubscriptionBirthday renvoie une valeur qui peut être null.

Or cela déclenche l'erreur clone.nonObject qui dit qu'il n'est pas possible d'appeler clone depuis null.

PHPStan remontera toujours l'erreur même si cette ligne est dans un traitement qui vérifie en amont que la date de l'objet n'est pas null car le typage retourné par la méthode indique qu'elle peut retourner null.

Voici donc un exemple de comment documenter correctement un faux positif :

// qa: Faux positif déclenché par valeur null mais qui ne l'est pas ici @phpstan-ignore clone.nonObject
$nextSubscriptionBirthday = clone $organization->getNextSubscriptionBirthday();

Format à retenir du commentaire :

// qa: Faux positif %explication complémentaire% @phpstan-ignore %code identifier%

L'explication du commentaire doit est obligatoirement avant le code identifier sinon le phpstan-ignore interprétera la suite comme le code, c'est pourquoi il est placé à la fin.

Scénario volontaire multi fichier si la règle a moins de sens

Certains fichiers de test peuvent déjà être très verbeux (fixtures, initialisations d'objets complexes). Ajouter un @phpstan-ignore sur chaque ligne concernée alourdit le code sans bénéfice réel, surtout quand l'erreur est structurelle au contexte (ex : une méthode dont le retour peut être null utilisée dans une fixture d'initialisation).

Dans ce cas, il est possible de déclarer une règle ignoreErrors dans le phpstan.neon limitée à un dossier ou fichier précis, en ciblant l'identifier de l'erreur :

ignoreErrors:
    # method.nonObject ignoré dans tests/ : les fixtures initialisent des objets partiels
    # dont certaines methodes peuvent retourner null avant d'etre completement renseignes.
    -
        identifier: method.nonObject
        path: tests/

Cela supprime les erreurs "Cannot call method X on Y|null" dans tout le dossier tests/, ce qui est acceptable : dans un contexte de test, les fixtures construisent souvent des objets de façon volontairement incomplète, et PHPStan ne peut pas distinguer un vrai null problématique d'une initialisation intermédiaire. Cette configuration est à documenter en commentaire dans phpstan.neon pour expliquer pourquoi la règle est écartée sur ce périmètre.