WP PHPStan

Quand l'utiliser

Utilisez cette skill lors du travail sur PHPStan dans une codebase WordPress, par exemple :

• configuration ou mise à jour de phpstan.neon / phpstan.neon.dist
• génération ou mise à jour de phpstan-baseline.neon
• correction des erreurs PHPStan via PHPDoc compatible WordPress (requêtes REST, hooks, résultats de requêtes)
• gestion sécurisée des classes de plugins/thèmes tiers (stubs/autoload/ignores ciblés)

Entrées requises

• résultat de wp-project-triage (à exécuter d'abord si vous ne l'avez pas fait)
• Si l'ajout/la mise à jour des dépendances Composer de développement est autorisé (stubs)
• Si la modification de la baseline est autorisée pour cette tâche

Procédure

0) Découvrir les points d'entrée PHPStan (déterministe)

1. Inspecter la configuration PHPStan (config, baseline, scripts) :
   • node skills/wp-phpstan/scripts/phpstan_inspect.mjs

Préférez le script composer existant du dépôt (par ex. composer run phpstan) quand il est présent.

1) S'assurer que les stubs du cœur WordPress sont chargés

szepeviktor/phpstan-wordpress ou php-stubs/wordpress-stubs sont effectivement requis pour la plupart des dépôts de plugins/thèmes WordPress. Sans cela, attendez-vous à un grand volume d'erreurs sur les fonctions du cœur WordPress inconnues.

• Confirmer que le package est installé (voir composer.dependencies dans le rapport d'inspection)
• S'assurer que la config PHPStan référence les stubs (voir references/third-party-classes.md)

2) S'assurer d'une phpstan.neon saine pour les projets WordPress

• Garder paths focalisé sur le code propriétaire (répertoires plugin/thème)
• Exclure le code généré et vendorisé (vendor/, node_modules/, artefacts de build, tests sauf analyse explicite)
• Garder les entrées ignoreErrors étroites et documentées

Voir :

• references/configuration.md

3) Corriger les erreurs avec le typage spécifique WordPress (préféré)

Préférez corriger les types plutôt que d'ignorer les erreurs. Motifs WordPress courants qui ont besoin d'aide :

• Points de terminaison REST : typer les paramètres de requête en utilisant WP_REST_Request<...>
• Callbacks de hooks : ajouter des types @param précis pour les arguments de callback
• Résultats de base de données et itérables : utiliser des formes de tableau ou des formes d'objet pour les résultats de requête
• Action Scheduler : typer les formes de tableau $args pour les callbacks de job

Voir :

• references/wordpress-annotations.md

4) Gérer les classes de plugins/thèmes tiers (seulement si nécessaire)

Lors de l'intégration avec des plugins/thèmes non présents dans l'environnement d'analyse :

• Confirmez d'abord que la dépendance est réelle (installée/requise)
• Préférez les stubs spécifiques au plugin déjà utilisés dans le dépôt (exemples courants : php-stubs/woocommerce-stubs, php-stubs/acf-pro-stubs)
• Si PHPStan ne peut toujours pas résoudre les classes, ajouter des patterns ignoreErrors ciblés pour le préfixe vendor spécifique

Voir :

• references/third-party-classes.md

5) Gestion de la baseline (utiliser comme outil de migration, pas comme poubelle)

• Générer une baseline une fois pour le code legacy, puis la réduire au fil du temps
• Ne pas « mettre en baseline » les erreurs nouvellement introduites

Voir :

• references/configuration.md

Vérification

• Exécuter PHPStan en utilisant la commande découverte (composer run ... ou vendor/bin/phpstan analyse)
• Confirmer que le fichier de baseline (s'il est utilisé) est inclus et n'a pas augmenté de manière inattendue
• Relancer après modification de ignoreErrors pour s'assurer que les patterns ne masquent pas des problèmes non liés

Modes de défaillance / débogage

• « Classe non trouvée » :
  • confirmer l'autoloading/stubs, ou ajouter un pattern ignore étroit
• Énorme nombre d'erreurs après activation de PHPStan :
  • réduire paths, ajouter excludePaths, commencer à un niveau inférieur, puis augmenter progressivement
• Types incohérents autour des hooks / paramètres REST :
  • ajouter un PHPDoc explicite (voir références) plutôt que des gardes runtime

Escalade

• Si un type dépend d'une API de plugin tiers que vous ne pouvez pas confirmer, demander la version de la dépendance ou la source avant d'inventer des types
• Si la correction nécessite l'ajout de nouvelles dépendances Composer (stubs/extensions), confirmez-le avec l'utilisateur d'abord