Comment analyser statiquement des projets PHP avec PHPStan –

PHPStan est un système d’analyse statique pour les projets PHP. Il trouve des bogues dans votre base de code en inspectant les fichiers source. Vous n’avez pas besoin d’exécuter votre code ou d’écrire manuellement des tests pour découvrir les problèmes!

Le terme «analyse statique» est défini comme un code de débogage sans réellement l’exécuter. Il est le plus souvent utilisé avec des langages interprétés, tels que PHP, car les problèmes qu’il trouve ont tendance à apparaître au stade de la compilation dans les langages compilés.

L’analyse statique a tendance à donner les meilleurs résultats lorsqu’elle est exécutée dans une base de code bien structurée et fortement typée. La documentation de PHPStan indique que le «code orienté objet moderne» est celui qui en bénéficiera le plus, car ces projets donnent à PHPStan plus d’informations sur lesquelles travailler.

Ajouter PHPStan à votre projet

Pour exécuter PHPStan, vous aurez besoin de PHP 7.1 ou plus récent. Cette exigence s’applique uniquement à la version de PHP utilisée pour exécuter PHPStan lui-même. L’outil est capable d’analyser les fichiers sources ciblant les anciennes versions de PHP.

Il est recommandé d’utiliser Composer pour ajouter PHPStan en tant que dépendance:

composer require --dev phpstan/phpstan

Le binaire PHPStan sera ajouté à votre projet à vendor/bin/phpstan. Vous pouvez maintenant l’utiliser pour analyser votre base de code pour la première fois:

vendor/bin/phpstan analyse src

La commande ci-dessus exécutera les tests de PHPStan sur tous les fichiers source de votre src annuaire. En fonction de la taille de votre base de code, cette opération peut prendre quelques minutes.

Vous verrez un vert « [OK] Aucune erreur »si tous les tests réussissent. Sinon, la liste des erreurs rencontrées sera affichée. Suivez les instructions affichées pour résoudre chaque erreur avant de réexécuter PHPStan.

Types et niveaux d’erreur

PHPStan comprend une pléthore de contrôles couvrant une grande variété de problèmes de base de code possibles. Certains des plus courants que vous rencontrerez sont les suivants:

• Problèmes de système de type – Attribuer une valeur non valide à une propriété typée ou transmettre des paramètres mal typés à une méthode. Cela inclut également les problèmes de contrat, tels qu’une classe implémentant de manière incorrecte une interface.
• Invocations de fonction – Passer trop ou pas assez de paramètres lors de l’appel d’une fonction ou d’une méthode (par exemple 3 au lieu de 4).
• Classes, méthodes et fonctions inconnues – Essayer d’utiliser quelque chose qui n’existe pas dans la base de code.
• Accès à des variables non définies / éventuellement non définies – Essayer d’utiliser une variable qui n’est pas définie dans une portée donnée, ou qui peut ne pas toujours avoir une valeur mais qui est utilisée dans un contexte où l’on est supposé.
• Vérification du code mort – Marquage de code inutile, comme les comparaisons booléennes qui résoudront toujours la même valeur et les branches de code qui ne seront jamais exécutées (par exemple, code suivant un return déclaration dans les fonctions).

Les règles sont classées en 9 «niveaux» différents, étiquetés de 0 à 8. Le niveau spécial max agit comme un alias pour le niveau le plus élevé possible. Au fil du temps, PHPStan peut ajouter des niveaux numériques supplémentaires, donc en utilisant max garantit que vous obtenez toujours les contrôles les plus stricts possible.

Par défaut, PHPStan exécute le niveau 0. Cela inclut uniquement les tests les plus fondamentaux. C’est une bonne idée que votre base de code passe chaque niveau individuellement avant de passer au suivant. Les projets matures sont susceptibles de se heurter à un autre ensemble de problèmes à chaque nouveau niveau.

Pour changer le niveau utilisé par PHPStan, vous pouvez passer le --level paramètre de ligne de commande:

vendor/bin/phpstan analyse src --level 8

En plus des vérifications intégrées, des extensions PHPStan sont disponibles pour ajouter encore plus de fonctionnalités. Vous pouvez également rédiger vos propres règles à partir de zéro. Cela est utile lorsque vous désapprouvez une fonctionnalité que les développeurs ne devraient plus utiliser dans un nouveau code. Nous aborderons la création de règles personnalisées dans un prochain article.

Configuration de PHPStan

Au-delà de l’expérimentation initiale, l’utilisation de l’interface de ligne de commande de PHPStan peut rapidement devenir fastidieuse. Il est préférable d’ajouter un fichier de configuration à votre projet qui peut ensuite être validé dans le contrôle de code source pour que tous vos développeurs l’utilisent.

PHPStan utilise le format de fichier de configuration Neon, qui a une syntaxe très similaire à YAML. Créer un phpstan.neon fichier dans le répertoire racine de votre projet. Ce fichier est automatiquement chargé à chaque démarrage de PHPStan, vous pouvez donc maintenant exécuter le analyse commande sans autre argument:

vendor/bin/phpstan analyse

Pour remplacer le fichier de configuration utilisé, passez le --configuration drapeau:

vendor/bin/phpstan analyse --configuration /phpstan-config.neon

Vous devez maintenant remplir votre phpstan.neon fichier avec du contenu. Un bon point de départ pourrait ressembler à ceci:

parameters:
  level: 0
  paths:
    - src

Ce fichier de configuration de base doit donner le même résultat que l’invocation de ligne de commande indiquée précédemment. Vous pouvez ajouter des répertoires supplémentaires à analyser en tant que nouvelles lignes dans le paths section. Pour exclure des fichiers et des répertoires, ajoutez-les à un excludes_analyse feuille dans le même parameters section.

Ignorer les erreurs

Parfois, PHPStan peut faire apparaître un problème inévitable. S’il y a un problème que vous ne pouvez pas résoudre immédiatement, vous souhaiterez peut-être l’ignorer explicitement afin de permettre aux tests de passer.

Ceci est particulièrement important lorsque vous souhaitez passer à un autre niveau de vérification ou que vous utilisez PHPStan dans un environnement CI où un échec de l’exécution arrêtera le déploiement de votre build. Même dans ce cas, ne prenez pas ce plan d’action à la légère – vous ne devriez choisir d’ignorer une erreur signalée que si vous êtes certain que cela ne sera pas dangereux.

Une fois que vous avez pris la décision, ajoutez un nouveau ignoreErrors section dans le parameters de votre fichier de configuration. Vous devez définir le message à associer, en tant que regex, et les chemins auxquels appliquer l’exclusion:

parameters:
  level: 0
  paths:
    - src
  ignoreErrors:
    - message: '/Return type string of method ExampleClass::example() is not covariant(.*).'
      path: src/ExampleClass.php

Vous pouvez éventuellement spécifier paths comme un tableau de chemins, remplaçant le seul path clé illustrée ci-dessus.

Règles facultatives

La rigueur de PHPStan peut être ajustée par une série de variables de configuration. Celles-ci vous permettent d’affiner les contrôles qui sont effectués, en dehors du système de niveaux décrit ci-dessus. Certains d’entre eux sont potentiellement controversés ou peu susceptibles de s’aligner sur tous les guides de style privés, ils sont donc désactivés par défaut.

Voici quelques paramètres qui pourraient valoir la peine d’être activés:

• checkAlwaysTrueInstanceof – Drapeaux des utilisations de instanceof qui sera toujours évalué à true.
• checkAlwaysTrueStrictComparison – Drapeaux lorsqu’une expression utilisant === ou !== évaluera toujours à true.
• checkFunctionNameCase – S’assure que la casse des noms de fonction correspond à leur définition lorsqu’ils sont appelés dans toute la base de code.
• polluteScopeWithLoopInitialAssignments – Lorsqu’il est réglé sur false (ses true par défaut), les variables déclarées dans les instructions de boucle initiales (par exemple $i dans $for ($i = 1; $i < 10; $i++)) ne sont pas accessibles en dehors du bloc de code de la boucle, évitant ainsi une éventuelle pollution de la portée parent.
• reportStaticMethodSignatures – Applique la vérification de type complet pour les paramètres et les types de retour dans les méthodes statiques en cas de substitution par une classe enfant.

Des détails complets sur ces paramètres facultatifs – et bien d’autres – peuvent être trouvés dans la référence de configuration de PHPStan.

Conclusion

C’est la fin de notre introduction à PHPStan. Cela vous aide à avoir confiance en votre base de code et met en évidence les problèmes possibles avant qu’ils ne deviennent un problème en production.

PHPStan est si rapide à installer qu’il n’y a vraiment aucune raison de ne pas l’utiliser, en particulier lorsque vous travaillez avec une base de code moderne fortement typée. Ne soyez pas trompé en pensant que cela peut remplacer les tests manuels. PHPStan peut se vanter d’un large assortiment de chèques, mais il ne peut pas identifier les problèmes logiques et ne comprend pas les règles métier de votre projet. Il s’agit simplement d’un autre atout de votre boîte à outils lors de l’évaluation de la santé d’une base de code, aux côtés de compagnons de confiance tels que les tests unitaires et les tests de fonctionnalités de bout en bout.