# PHPStan 2.0 et WordPress : ce qui change dans votre configuration

> Les nouveautés de PHPStan 2.0, l'apparition du niveau 10, et l'impact concret sur phpstan-wordpress et vos fichiers de configuration existants.

- Auteur : Clément Hadrot
- Publié le : 2024-12-24
- Mis à jour le : 2024-12-24
- Catégorie : Tests
- URL : https://wpmoderne.dev.wordpress-developpement.fr/tests/phpstan-2-0-wordpress/

## L’essentiel

- PHPStan 2.0 reste rétrocompatible avec la plupart des configurations 1.x
- Le niveau 10 traque désormais les types de retour implicitement mixtes
- phpstan-wordpress nécessite une mise à jour vers sa branche compatible

Chaque montée de version majeure de PHPStan provoque le même petit moment d'angoisse dans l'équipe : est-ce que la CI va soudainement s'effondrer sous des centaines de nouvelles erreurs ? Avec PHPStan 2.0, la réponse est plus rassurante que redoutée, mais la mise à jour n'est pas non plus totalement transparente sur un projet WordPress, en particulier à cause de la dépendance à l'extension `phpstan-wordpress` qui déclare les globales et les types spécifiques au cœur.

On a fait la mise à jour sur trois projets d'agence de tailles différentes, du petit thème enfant à l'extension e-commerce de plusieurs dizaines de milliers de lignes, pour comprendre concrètement ce qui change et ce qu'il faut prévoir avant de lancer la mise à jour sur un projet en production.

## Ce qui ne change presque pas

Bonne nouvelle en premier lieu : la structure du fichier `phpstan.neon`, les niveaux de 0 à 9 déjà connus, et la logique générale d'analyse restent identiques. Un projet déjà correctement configuré en 1.x continue de tourner sans modification immédiate après la mise à jour de la dépendance Composer, ce qui a permis une migration progressive plutôt qu'un big bang risqué.

## La vraie nouveauté : le niveau 10

PHPStan 2.0 introduit un dixième niveau d'analyse, plus strict que le niveau 9 qui était jusque-là le maximum. Ce niveau supplémentaire traque en particulier les types de retour implicitement `mixed`, c'est-à-dire les fonctions et méthodes dont PHPStan ne peut déduire aucun type de retour précis faute d'annotation ou de déclaration de type explicite.

```
// Signalé au niveau 10 : type de retour implicite
function recuperer_meta_produit( $produit_id, $cle ) {
    return get_post_meta( $produit_id, $cle, true );
}

// Corrigé : type de retour explicite
function recuperer_meta_produit( int $produit_id, string $cle ): mixed {
    return get_post_meta( $produit_id, $cle, true );
}
```

Sur du code WordPress, ce niveau se révèle particulièrement exigeant, car de nombreuses fonctions du cœur elles-mêmes retournent des types composites peu précis (une chaîne, un tableau, ou `false` selon les cas), ce qui remonte en cascade dans tout code qui les enveloppe sans déclaration de type stricte.

> L'essentiel à retenir : PHPStan 2.0 reste rétrocompatible avec la plupart des configurations 1.x ; Le niveau 10 traque désormais les types de retour implicitement mixtes ; phpstan-wordpress nécessite une mise à jour vers sa branche compatible

## Mettre à jour phpstan-wordpress

L'extension communautaire `szepeviktor/phpstan-wordpress`, qui fournit les stubs déclarant les types des fonctions et globales du cœur, doit être mise à jour vers sa branche compatible avec PHPStan 2.0 : les versions antérieures déclenchent des erreurs de compatibilité d'extension au démarrage, avant même la première analyse du code.

```
composer require --dev szepeviktor/phpstan-wordpress:^2.0 phpstan/phpstan:^2.0
```

Il faut vérifier en parallèle la compatibilité des autres extensions PHPStan utilisées dans le projet, notamment celles fournissant des stubs pour WooCommerce ou Advanced Custom Fields lorsqu'elles sont utilisées, car certaines n'avaient pas encore publié de version compatible au moment de la sortie de PHPStan 2.0, ce qui a obligé un des trois projets testés à retarder sa mise à jour de plusieurs semaines.

## Impact sur la baseline existante

Un projet qui utilisait déjà une baseline pour ignorer les erreurs historiques (via `phpstan analyse --generate-baseline`) doit la régénérer après la mise à jour : le format interne a légèrement évolué, et certaines erreurs auparavant ignorées peuvent désormais être reformulées différemment par le nouveau moteur, ce qui empêche la baseline existante de les faire correspondre correctement.

```
vendor/bin/phpstan analyse --generate-baseline=phpstan-baseline.neon.dist
```

Sur le projet le plus volumineux testé, la régénération de la baseline a fait apparaître une trentaine de nouvelles erreurs par rapport à l'ancienne, toutes liées au changement de formulation de certains messages plutôt qu'à de véritables nouvelles détections.

## Options de configuration renommées

Quelques options de configuration ont changé de nom ou de comportement par défaut entre les deux versions majeures, ce qui génère des avertissements de dépréciation plutôt que des erreurs bloquantes au premier lancement :

- `checkGenericClassInNonGenericObjectType` devient activé par défaut, ce qui peut faire remonter de nouvelles alertes sur des annotations de tableaux typés imprécises
- Le comportement de résolution des types union avec `false` a été légèrement affiné, ce qui affecte les fonctions du cœur WordPress qui retournent classiquement une valeur ou `false` en cas d'échec

> Passer directement au niveau 10 sur un projet WordPress existant est rarement réaliste à court terme : mieux vaut consolider d'abord le niveau 8 ou 9, puis n'envisager le niveau 10 que sur du code neuf, écrit avec des types stricts dès le départ.

## Notre recommandation de séquence de migration

1. Mettre à jour PHPStan et `phpstan-wordpress` ensemble, jamais l'un sans l'autre
2. Relancer l'analyse au niveau actuellement configuré, sans changer de niveau dans la même étape
3. Régénérer la baseline si le projet en utilise une, et comparer le nombre d'entrées avant et après
4. Envisager le niveau 10 uniquement sur un module isolé et récent, jamais sur l'ensemble d'un projet legacy en une seule fois

## En résumé

La migration vers PHPStan 2.0 sur un projet WordPress reste globalement maîtrisable, à condition de traiter la mise à jour de `phpstan-wordpress` comme une étape à part entière, pas comme un simple effet de bord de la mise à jour de PHPStan lui-même. Le niveau 10, la nouveauté la plus visible de cette version, reste un objectif de moyen terme pour la majorité des projets existants, plutôt qu'une case à cocher immédiatement après la mise à jour.