wp-phpstan

Aperçu de la skill wp-phpstan

wp-phpstan est la skill à օգտագործer quand vous avez besoin que PHPStan fonctionne vraiment bien dans une base de code WordPress, et pas seulement qu’il « s’exécute à peu près ». Elle s’adresse aux développeurs de plugins, de thèmes et de sites qui veulent une analyse statique plus propre, moins de faux positifs, et une voie pratique pour traiter le code legacy qui comporte déjà des problèmes.

L’objectif principal est la configuration et la correction : brancher phpstan.neon, gérer les baselines, charger les stubs WordPress et ajouter les annotations de type adaptées à WordPress lorsque PHPStan ne peut pas déduire le comportement à l’exécution.

Ce pour quoi wp-phpstan est le plus adapté

Utilisez la skill wp-phpstan quand vous devez :

• installer ou mettre à jour PHPStan dans un dépôt WordPress
• réduire les erreurs causées par des symboles du core WordPress absents
• gérer phpstan-baseline.neon sans masquer les nouvelles régressions
• corriger les patterns dynamiques de WordPress comme les hooks, les requêtes REST et les résultats de requêtes
• composer avec des classes optionnelles de plugins tiers comme WooCommerce ou ACF

Pourquoi cette skill est différente

Un prompt PHPStan générique passe souvent à côté des contraintes propres à WordPress : classes chargées à l’exécution, callbacks de hooks, dépendances de plugins et environnements d’analyse qui ne correspondent pas au site en production. wp-phpstan est utile parce qu’elle traite d’abord ces cas limites, en particulier le chargement des stubs et les ignores ciblés.

Quand ne pas l’utiliser

Si vous avez seulement besoin d’une explication rapide et ponctuelle d’une commande PHPStan, cette skill est peut-être plus qu’il ne vous faut. Elle est surtout utile lorsque la qualité de l’analyse compte suffisamment pour que les choix de configuration, la politique de baseline et les indices de type influencent réellement le résultat.

Comment utiliser la skill wp-phpstan

Installer et vérifier la skill

Pour wp-phpstan install, ajoutez la skill depuis le dépôt WordPress agent skills :

npx skills add WordPress/agent-skills --skill wp-phpstan

Après l’installation, lisez d’abord SKILL.md, puis les références associées et le script d’inspection. Le dépôt est structuré pour répondre aux questions qui comptent le plus pour l’adoption : ce que PHPStan voit, ce qu’il ignore et ce qu’il faut typer plutôt que supprimer.

Donner les bons éléments d’entrée à la skill

La skill wp-phpstan donne les meilleurs résultats si vous fournissez le contexte du projet avant de demander des corrections. Commencez par :

• la sortie de wp-project-triage
• la possibilité ou non de modifier les dépendances Composer de développement
• l’autorisation ou non de mettre à jour la baseline
• les erreurs PHPStan précises ou le fichier de configuration que vous voulez modifier

Un mauvais prompt : « Corrige PHPStan dans mon plugin WordPress. »

Un meilleur prompt : « Utilise wp-phpstan pour inspecter la configuration PHPStan actuelle de mon plugin, confirmer si szepeviktor/phpstan-wordpress est chargé, et proposer le changement de config le plus petit possible pour corriger les fonctions WordPress inconnues sans ignores trop larges. Les changements de baseline sont autorisés uniquement pour les erreurs legacy déjà présentes. »

Flux de travail recommandé et fichiers à consulter

Pour un wp-phpstan usage pratique, suivez le chemin de décision du dépôt :

1. inspectez la configuration avec scripts/phpstan_inspect.mjs
2. vérifiez les fichiers principaux de configuration et de baseline
3. consultez references/configuration.md
4. lisez references/third-party-classes.md
5. utilisez references/wordpress-annotations.md quand le problème vient de l’inférence de types, pas de la configuration

Si vous voulez aller vite vers un bon résultat, prévisualisez d’abord ces fichiers :

• SKILL.md
• references/configuration.md
• references/third-party-classes.md
• references/wordpress-annotations.md
• scripts/phpstan_inspect.mjs

Forme de prompt conseillée

Les bons prompts indiquent à la skill ce qui est figé, ce qui est flexible et le résultat attendu. Par exemple :

• « Audite mon phpstan.neon pour un plugin WordPress et dis-moi s’il faut ajouter des stubs, resserrer ignoreErrors ou mettre à jour la baseline. »
• « Réécris cette annotation de contrôleur REST pour que PHPStan comprenne la forme de la requête. »
• « Mon environnement d’analyse n’inclut pas WooCommerce ; propose une stratégie étroite de stubs/ignores pour ces classes manquantes. »

Ce niveau de précision aide wp-phpstan à choisir entre modifications de configuration, annotations ou changements de dépendances.

FAQ de la skill wp-phpstan

wp-phpstan est-elle réservée aux plugins WordPress ?

Non. La skill wp-phpstan convient aussi aux thèmes et aux sites WordPress avec du code personnalisé. Elle est particulièrement utile partout où PHPStan a besoin d’aide pour comprendre le comportement WordPress à l’exécution.

Faut-il déjà avoir Composer et PHPStan installés ?

Oui, cette skill suppose un flux de travail PHPStan basé sur Composer. Si votre dépôt n’utilise pas Composer, ou si PHPStan ne fait pas partie de la chaîne d’outils, la skill ne sera pas un bon choix.

Est-ce mieux qu’un prompt personnalisé ?

En général oui, si vous tenez à des décisions de configuration reproductibles. Un prompt personnalisé peut résoudre une erreur isolée, mais wp-phpstan fournit un meilleur flux de travail pour les baselines, les stubs et le typage spécifique à WordPress.

Quand faut-il éviter les ignores trop larges ?

Évitez les ignores trop larges quand la classe ou la fonction existe en réalité via un stub manquant, un problème d’autoload ou un décalage entre l’environnement d’analyse et celui du site. N’utilisez des ignores ciblés qu’après avoir vérifié que la dépendance est bien présente et qu’elle ne peut pas être corrigée proprement.

Comment améliorer la skill wp-phpstan

Donnez-lui le vrai mode de défaillance PHPStan

Les meilleurs résultats avec wp-phpstan viennent du fait d’identifier le type d’échec avant de demander une correction :

• fonctions du core WordPress inconnues → stubs ou configuration
• bruit legacy → workflow de baseline
• données de requête dynamiques → @phpstan-param ou aliases de types réutilisables
• API de plugins optionnels → stubs ciblés ou ignores étroits

Si vous ne collez qu’une liste d’erreurs, la skill risque d’optimiser le symptôme plutôt que la cause.

Partagez le périmètre d’analyse

Dites à la skill ce qu’elle a le droit de modifier. Les résultats s’améliorent quand vous précisez :

• peut-elle modifier composer.json ?
• peut-elle ajouter des dépendances de développement ?
• peut-elle changer phpstan.neon ?
• peut-elle régénérer la baseline ?

Ces permissions déterminent si wp-phpstan doit privilégier des corrections de code, de configuration ou de dépendances.

Préférez des entrées concrètes à des objectifs vagues

Une entrée plus précise produit une meilleure sortie. Par exemple, incluez :

• le niveau PHPStan actuel
• les répertoires analysés
• si le core WordPress est présent dans la CI
• le plugin ou la classe exacts qui provoquent les erreurs de symboles manquants

Cela aide la skill wp-phpstan à recommander le bon chemin d’installation et d’usage pour le Backend Development, au lieu de fournir une checklist PHPStan générique.

Itérez de la configuration vers les annotations

Un bon wp-phpstan guide suit généralement cet ordre :

1. vérifier les stubs et la découverte
2. resserrer les excludes et les ignores
3. annoter les types dynamiques propres à WordPress
4. mettre à jour la baseline uniquement pour la dette legacy acceptée

Cet ordre permet de garder une analyse assez stricte pour détecter les nouveaux problèmes, tout en réduisant les faux positifs là où le modèle dynamique de WordPress bloque l’inférence.