02. Niveaux 0 à 10 et maîtrise de mixed

Comprendre le mécanisme

Les niveaux PHPStan sont cumulatifs : un niveau supérieur ajoute des vérifications à ceux qui le précèdent. Au référentiel vérifié pour ce cours, ils vont de 0 à 10 ; le niveau 9 restreint fortement le mixed explicite et le niveau 10 étend la sévérité au mixed implicite. L’alias max suit le plus haut niveau lors des évolutions de l’outil, ce qui demande une politique d’upgrade.

Raisonner et vérifier

mixed représente une information absente ou très générale ; un cast ou un PHPDoc inventé ne constitue pas une validation d’entrée. Réduisez l’incertitude par des gardes et des contrats précis aux frontières. Montez le niveau par étapes suivies, avec critères d’acceptation et budget de correction. Un niveau élevé ne démontre ni absence d’injection ni autorisation correcte : ces propriétés dépassent le typage seul.

Niveaux cumulatifs

Les niveaux sont cumulatifs. La sévérité s’ajoute au socle antérieur. Monter de niveau conserve les contrôles précédents. Gardez une fixture de diagnostic déjà détecté au niveau inférieur pour vérifier que votre changement de configuration n’a pas accidentellement retiré des règles utiles.

Échelle 0 à 10

PHPStan 2.x propose des niveaux de 0 à 10. Le référentiel du cours inclut les niveaux 9 et 10. Dans PHPStan 2.x, zéro est le point d’entrée le plus permissif et dix le plus strict de cette échelle. La version doit accompagner cette indication afin d’éviter une promesse valable pour toute version future.

Valeur max

max suit le plus haut niveau disponible. Une mise à jour peut ajouter des contrôles au plus haut niveau. Le mot max suit le sommet disponible après mise à jour. Une release de l’outil peut donc ajouter du travail ; examinez les diagnostics dans une mise à jour dédiée et explicable.

Mixed explicite

Le niveau 9 restreint mixed explicite. L’objectif est de limiter les opérations sans type précis. Au niveau neuf, appeler name sur un mixed n’est pas justifié. Vérifiez une interface ou validez une structure puis accédez à son contrat, au lieu d’ajouter une annotation locale qui prétend savoir.

Mixed implicite

Le niveau 10 étend le contrôle au mixed implicite. Il augmente la sévérité sur les informations absentes. Le niveau dix ajoute des contrôles sur les valeurs restées mixed faute de déclaration. Corrigez les frontières et signatures, plutôt que rendre toutes les valeurs explicitement mixed pour changer seulement le diagnostic.

Réduction réelle

Une garde réelle peut réduire un type. La conversion ne vérifie pas nécessairement le contrat d’entrée. Après un instanceof sur une interface, ses méthodes deviennent disponibles dans la branche admise. Le chemin contraire doit retourner ou lever une exception avant tout appel qui exige ce contrat.

Type et permission

Un niveau élevé ne prouve pas les permissions métier. Le typage ne connaît pas automatiquement chaque règle d’accès. Un objet Reservation correctement typé peut appartenir à un autre client. Ajoutez une décision de périmètre sur acteur, tenant et ressource ; le niveau maximal ne fournit pas cette relation métier.

Progression planifiée

La montée de niveau doit avoir un plan de correction. La progression doit changer les contrats et comportements concernés. Choisissez un niveau cible, des propriétaires et un ordre de correction. Traitez d’abord les frontières très utilisées ; chaque étape doit garder les diagnostics nouveaux visibles et les tests fonctionnels exécutables.

Dette visible

Une baseline peut décrire de la dette. Elle reporte des diagnostics sans modifier le code. Une baseline permet de distinguer une dette connue du nouveau code. Elle doit rester revue et bornée ; régénérer automatiquement toutes les erreurs à chaque analyse détruirait cette distinction.

Vérification runtime

Les tests d’exécution complètent l’analyse. Les techniques ont des périmètres complémentaires. Une annotation précise peut mentir sur un résultat externe. Un test de parsing avec null, structure incomplète et mauvais type vérifie que le chemin d’exécution établit effectivement ce que l’analyse suppose.

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

<?php
declare(strict_types=1);
function label(mixed $value): string {
    return $value->name();
}

Le paramètre de l’extrait est explicitement mixed et le corps appelle une méthode sans vérifier son existence. Introduisez une interface si le contrat est connu, ou une garde réelle lorsque la frontière reste ouverte. Exécutez aussi le refus avec une valeur incompatible pour vérifier le comportement du programme.

La suppression masque l’incertitude. Une annotation mensongère ne valide pas l’entrée. mixed n’accorde pas toutes les capacités. L’opération doit être justifiée par un type réellement établi.

Travail pratique : Analysez une donnée JSON inconnue à différents niveaux puis remplacez un accès direct par une garde de structure.

Critères de correction : Comparez les diagnostics et vérifiez les refus à l’exécution avec null, tableau et chaîne. Documentez niveau retenu et raisons des écarts temporaires.