01. Installation et analyse reproductibles

Comprendre le mécanisme

PHPStan examine le code et ses types sans exécuter les parcours métier habituels. Son résultat dépend de sa version, de la configuration, des extensions, des chemins et de la cible PHP. Une installation locale de développement avec lock versionné rend le contrôle plus reproductible qu’un outil global mis à jour sans suivi. Distinguez le PHP qui exécute l’analyse et la version cible décrite par la configuration.

Raisonner et vérifier

Analysez les classes utiles et leurs contrats, avec les stubs ou extensions nécessaires. Une découverte de symboles mal configurée peut produire des erreurs trompeuses ; exclure massivement le code masque le problème. La pipeline doit échouer si l’analyse échoue et rendre les diagnostics exploitables. Ne publiez pas les secrets du fichier d’environnement pour obtenir un rapport de types.

Version de l’analyseur

La version de PHPStan influence les diagnostics. Les versions peuvent faire évoluer les vérifications. Deux versions peuvent comprendre différemment une annotation ou ajouter un diagnostic. Enregistrez la version utilisée avec le rapport pour pouvoir reproduire le résultat lors d’une revue de release.

Dépendances verrouillées

Le lock aide à reproduire les dépendances. Il décrit les dépendances résolues, pas les credentials. Exécutez composer install à partir du lock révisé plutôt que résoudre de nouvelles versions à chaque job. Les extensions et leurs dépendances influencent aussi le résultat, pas seulement le binaire principal.

Version cible et runtime

La cible PHP doit être configurée correctement. L’analyse et le runtime sont des environnements distincts. phpVersion: 80400 décrit PHP 8.4 pour l’analyse. Cette configuration n’installe aucun interpréteur ; vérifiez séparément les versions de PHP en CLI, dans les workers et dans le serveur web.

Périmètre des chemins

Les chemins analysés déterminent la couverture. Un fichier exclu échappe aux contrôles concernés. Si seul src est analysé, un script d’import placé dans bin peut rester hors rapport. Inventoriez les points d’entrée et justifiez exclusions et code généré avant d’interpréter une suite verte.

Extensions de framework

Les extensions peuvent préciser des contrats de framework. La découverte de symboles doit correspondre aux bibliothèques. Une extension Symfony ou Doctrine décrit des comportements que le code dynamique rend difficiles à inférer. Vérifiez sa compatibilité et gardez un test d’exécution pour les services ou repositories réellement utilisés.

Échec observable

Une erreur d’analyse doit faire échouer la CI prévue. Le contrôle doit participer à la décision de qualité. Le pipeline doit respecter le code de sortie de l’analyseur. Une commande suivie de true peut imprimer des erreurs tout en laissant publier ; testez le job avec un défaut volontaire dans une branche de laboratoire.

Même configuration

Les configurations locale et CI doivent être cohérentes. La version et les options peuvent diverger. Un fichier local prioritaire peut masquer la configuration distribuée utilisée en CI. Appelez explicitement le fichier attendu et comparez niveau, chemins et extensions avant de conclure à une différence de comportement inexplicable.

Analyse sans parcours

L’analyse statique ne rejoue pas tous les parcours métier. Son périmètre diffère d’une exécution fonctionnelle. PHPStan raisonne sur le code et ses contrats ; il ne simule pas chaque demande utilisateur. Les permissions, courses concurrentes et effets prestataire doivent disposer d’autres preuves ciblées.

Sans secrets de production

Les secrets ne sont pas nécessaires à un rapport de types. Les diagnostics peuvent rester sans credentials réels. Ne chargez pas une connexion réelle simplement pour découvrir des types. Utilisez des contrats et une configuration de bootstrap minimale ; un analyseur ne doit pas devenir une voie d’accès aux données clientes.

Découverte des symboles

Une mauvaise découverte doit être corrigée à sa cause. L’exclusion masque la couverture au lieu de rétablir les symboles. Si une classe reste inconnue, contrôlez autoload, namespace et dépendances. Un ignore global ferait disparaître le symptôme tout en laissant l’analyse perdre des informations sur les appels concernés.

Atelier guidé : lire, expliquer et vérifier le code

parameters:
    level: 8
    phpVersion: 80400
    paths:
        - src

Lisez chaque clé de la configuration puis comparez-la aux commandes réellement exécutées en CI. La version cible n’est ni un gestionnaire de runtime ni une garantie de compatibilité de toutes les dépendances. Produisez un rapport reproductible à partir du même lock et du même fichier de configuration.

La valeur décrit la version cible, sans provisionner le runtime. Le paramètre n’installe aucun interpréteur. Seul src est explicitement dans les chemins montrés. Le typage ne remplace pas les scénarios exécutés.

Travail pratique : Exécutez l’analyse localement et en CI sur le même commit avec le même lock, puis introduisez un type de retour incohérent.

Critères de correction : Les deux environnements doivent signaler la régression et la CI doit retourner un échec. Conservez la version et le chemin de configuration dans le diagnostic, sans contenu sensible.