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 sources. 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 l'exécuter réellement. Il est le plus souvent utilisé avec des langages interprétés, tels que PHP, car les problèmes qu'il détecte 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 moderne orienté objet” en bénéficiera le plus, car ces projets donnent à PHPStan plus d'informations avec 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 dans vendor/bin/phpstan. Vous pouvez maintenant l'utiliser pour analyser votre base de code pour la première fois :
vendor/bin/phpstan analyze src
La commande ci-dessus exécutera les tests PHPStan sur tous les fichiers source de votre répertoire src. Selon la taille de votre base de code, cela peut prendre quelques minutes.
Vous verrez un vert “[OK] Aucune erreur” message si tous les tests réussissent. Sinon, la liste des erreurs rencontrées s'affichera. Suivez les instructions affichées pour résoudre chaque erreur avant de réexécuter PHPStan.
Types et niveaux d'erreur
PHPStan inclut une pléthore de vérifications couvrant une grande variété de problèmes de base de code possibles. Certains des problèmes les plus courants que vous rencontrerez sont les suivants :
- Problèmes de type système– Attribuer à une propriété typée une valeur non valide 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 incorrectement 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 un périmètre donné, ou qui peut ne pas toujours avoir de valeur mais qui est utilisée dans un contexte où l'on en suppose une.
- Vérification de code mort – Signalisation du 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, le code suivant une instruction de retour dans les fonctions).
Les règles sont classées en 9 “niveaux” différents, étiquetés de 0 à 8. Le niveau spécial max sert d'alias pour le niveau le plus élevé possible. Au fil du temps, PHPStan peut ajouter des niveaux numériques supplémentaires, donc l'utilisation de max garantit que vous obtenez toujours les contrôles les plus stricts possibles.
Par défaut, PHPStan exécute le niveau 0. Cela n'inclut que 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 rencontrer un autre ensemble de problèmes à chaque nouveau niveau.
Publicité
Pour changer le niveau utilisé par PHPStan, vous pouvez passer le paramètre de ligne de commande –level :
vendor/bin/phpstan analyze src –level 8
En plus du checks, des extensions PHPStan sont disponibles pour ajouter encore plus de fonctionnalités. Vous pouvez également écrire vos propres règles à partir de zéro. Ceci est utile lorsque vous désapprouvez des fonctionnalités que les développeurs ne devraient plus utiliser dans un nouveau code. Nous couvrirons 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 en 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 affecté au contrôle de code source pour que tous vos développeurs puissent l'utiliser.
PHPStan utilise le format de fichier de configuration Neon, qui a une syntaxe très similaire à YAML. Créez un fichier phpstan.neon dans le répertoire racine de votre projet. Ce fichier est automatiquement chargé à chaque démarrage de PHPStan, vous pouvez donc maintenant exécuter la commande analyze sans autre argument :
vendor/bin/phpstan analyze
Pour remplacer le fichier de configuration utilisé, passez l'indicateur –configuration :
vendor/bin/phpstan analyze –configuration /phpstan-config.neon
Vous devez maintenant remplir votre fichier phpstan.neon avec du contenu. Un bon point de départ pourrait ressembler à ceci :
paramètres : niveau : 0 chemins : – src publicité
Ce fichier de configuration de base doit donner le même résultat que l'appel de ligne de commande indiqué précédemment. Vous pouvez ajouter des répertoires supplémentaires à analyser en tant que nouvelles lignes dans la section des chemins. Pour exclure des fichiers et des répertoires, ajoutez-les à une feuille excludes_analyse dans la même section de paramètres.
Ignorer les erreurs
Parfois, PHPStan peut faire apparaître un problème qui est inévitable. S'il y a un problème que vous ne pouvez pas résoudre immédiatement, vous pouvez l'ignorer explicitement afin de permettre aux tests de réussir.
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 d'exécution arrêtera le déploiement de votre build. Même ainsi, ne prenez pas ce plan d'action à la légère – vous ne devez choisir d'ignorer une erreur signalée que si vous êtes certain de pouvoir le faire en toute sécurité.
Une fois que vous avez pris votre décision, ajoutez une nouvelle section ignoreErrors dans les paramètres de votre fichier de configuration. Vous devez définir le message à faire correspondre, en tant que regex, et les chemins auxquels appliquer l'exclusion :
paramètres : niveau : 0 chemins : – src ignoreErrors : – message : '/Return type string of method ExampleClass :: exemple() n'est pas covariant(.*).' chemin : src/ExampleClass.php
Vous pouvez éventuellement spécifier des chemins sous forme de tableau de chemins, remplaçant la clé de chemin unique indiquée ci-dessus.
Règles facultatives
< p>La rigueur de PHPStan peut être ajustée par une série de variables de configuration. Ceux-ci 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 avec tous les guides de style privés, ils sont donc désactivés par défaut.
Quelques paramètres qui pourraient valoir la peine d'être activés :
- checkAlwaysTrueInstanceof – Marque les utilisations d'instanceof qui seront toujours évaluées à true.
- checkAlwaysTrueStrictComparison – Signale lorsqu'une expression utilisant === ou !== sera toujours évaluée à true.
- checkFunctionNameCase – Assure que la casse des noms de fonction correspond à leur définition lorsqu'ils sont appelés dans la base de code.
- polluteScopeWithLoopInitialAssignments – Lorsqu'il est défini sur false (c'est vrai 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 à l'extérieur le bloc de code de la boucle, évitant une éventuelle pollution de la portée parent.
- rapportStaticMethodSignatures – Impose la vérification de type complète pour les paramètres et les types de retour dans les méthodes statiques lorsqu'elles sont remplacées par une classe enfant.
Publicité
Détails complets sur ces paramètres facultatifs – et bien d'autres – peut être trouvé dans la référence de configuration de PHPStan.
Conclusion
C'est la fin de notre introduction à PHPStan. Il 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 à configurer qu'il n'y a vraiment aucune raison de ne pas l'utiliser, surtout lorsque vous travaillez avec une base de code moderne fortement typée. Ne vous laissez pas tromper en pensant que cela peut remplacer les tests manuels. PHPStan peut proposer un large éventail de contrôles, mais il ne peut pas identifier les problèmes logiques et ne comprend pas les règles métier de votre projet. C'est simplement un autre atout dans votre boîte à outils lors de l'évaluation de la santé d'une base de code, servant aux côtés de compagnons de confiance tels que les tests unitaires et les tests de fonctionnalité de bout en bout.