wp-phpstan

wp-phpstan スキルの概要

wp-phpstan は、PHPStan を「とりあえず動かす」だけでなく、WordPress コードベースでちゃんと機能させたいときに使うスキルです。プラグイン、テーマ、サイト開発者向けで、よりきれいな静的解析、誤検知の削減、そして既に問題を抱えているレガシーコードに対する現実的な改善ルートを求める場合に向いています。

主な役割は、phpstan.neon の設定と修正です。phpstan.neon の配線、baseline の扱い、WordPress stubs の読み込み、そして PHPStan が実行時の挙動を推論できない箇所への WordPress-aware な型注釈の追加が中心になります。

wp-phpstan が最適なケース

wp-phpstan スキルは、次のような場合に使います。

• WordPress リポジトリで PHPStan を新規導入または更新したい
• WordPress core のシンボル不足によるエラーを減らしたい
• 新しい退行を隠さずに phpstan-baseline.neon を管理したい
• hooks、REST requests、query results などの動的な WordPress パターンを修正したい
• WooCommerce や ACF のような、任意導入のサードパーティ plugin クラスを扱いたい

このスキルが他と違う理由

汎用的な PHPStan プロンプトでは、WordPress 特有の制約を見落としがちです。たとえば、実行時に読み込まれるクラス、hook コールバック、plugin 依存関係、そして実際のサイトと一致しない解析環境などです。wp-phpstan はこうした境界条件を最優先で扱うため、特に stub の読み込みと、狙いを絞った ignore の設計に強みがあります。

使わないほうがよいケース

PHPStan の単発コマンドをさっと知りたいだけなら、このスキルはやや大げさかもしれません。setup の選び方、baseline の運用方針、型ヒントが結果に影響するレベルで解析品質を重視するときに、最も価値を発揮します。

wp-phpstan スキルの使い方

スキルをインストールして確認する

wp-phpstan install を使う場合は、WordPress agent skills repo からスキルを追加します。

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

インストール後は、まず SKILL.md を読み、そのあとに補助リファレンスと inspection script を確認します。この repo は、導入判断に最も影響する問い、つまり PHPStan が何を見て、何を無視し、何を suppress するのではなく型付けすべきかに答える構成になっています。

スキルに適切な入力を渡す

wp-phpstan は、修正を依頼する前にプロジェクト文脈を渡すと最もよく機能します。まずは次の情報をそろえてください。

• wp-project-triage の出力
• Composer の dev dependencies を変更してよいかどうか
• baseline の更新を許可するかどうか
• 変更したい具体的な PHPStan エラーまたは config file

弱いプロンプト例: “Fix PHPStan in my WordPress plugin.”

より強いプロンプト例: “Use wp-phpstan to inspect my plugin’s current PHPStan setup, confirm whether szepeviktor/phpstan-wordpress is loaded, and propose the smallest config change that fixes unknown WordPress functions without broad ignores. Baseline changes are allowed only for existing legacy errors.”

推奨ワークフローとファイル

実用的な wp-phpstan usage では、repo 独自の判断手順に従うのが近道です。

1. scripts/phpstan_inspect.mjs で setup を確認する
2. メインの config と baseline files を確認する
3. references/configuration.md を読む
4. references/third-party-classes.md を読む
5. 問題が setup ではなく型推論なら references/wordpress-annotations.md を使う

最短で良い結果を出したいなら、先に次のファイルをざっと見ておくとよいです。

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

実用的なプロンプトの形

良いプロンプトは、何が固定で、何が変更可能で、どんな出力がほしいのかを明確に伝えます。たとえば次のような形です。

• “Audit my phpstan.neon for a WordPress plugin and tell me whether I should add stubs, tighten ignoreErrors, or update the baseline.”
• “Rewrite this REST controller annotation so PHPStan understands the request shape.”
• “My analysis environment does not include WooCommerce; propose a narrow stub/ignore strategy for these missing classes.”

ここまで具体的に伝えると、wp-phpstan は config changes、annotations、dependency changes のどれを選ぶべきか判断しやすくなります。

wp-phpstan スキル FAQ

wp-phpstan は WordPress plugin 専用ですか？

いいえ。wp-phpstan スキルは theme や、カスタムコードを含む WordPress site にも適しています。WordPress の runtime behavior を PHPStan に理解させる必要がある場面なら、広く有効です。

Composer と PHPStan はもう入っている必要がありますか？

はい。このスキルは Composer ベースの PHPStan ワークフローを前提にしています。repo が Composer を使っていない場合、または PHPStan が toolchain に含まれていない場合は、あまり適した選択ではありません。

自分でカスタムプロンプトを書くよりよいですか？

たいていは yes です。特に、再現可能な setup decisions を重視するならその差が出ます。カスタムプロンプトでも単発のエラーは直せますが、wp-phpstan のほうが baseline、stub、WordPress-specific な型付けを含む、より実務的なワークフローを取りやすくなります。

broad ignores を避けるべきなのはどんなときですか？

class や function が本当に使えるのに見えていないだけなら、broad ignores は避けてください。たとえば stub の不足、autoload の問題、analysis environment の不一致が原因のことがあります。依存経路が実在し、きれいには直せないと確認できた場合にのみ、狙いを絞った ignore を使うべきです。

wp-phpstan スキルをより良く使うには

本当の PHPStan failure mode を伝える

wp-phpstan で最良の結果を得るには、修正を頼む前に failure type を切り分けるのが重要です。

• unknown WordPress core functions → stubs または config
• legacy noise → baseline workflow
• dynamic request data → @phpstan-param または再利用可能な type aliases
• optional plugin APIs → targeted stubs または narrow ignores

エラー一覧だけを貼ると、スキルが原因ではなく症状の最適化に向かってしまうことがあります。

解析の境界条件を共有する

スキルに、何を変更してよいかを伝えてください。たとえば次の指定があると精度が上がります。

• composer.json を編集してよいか
• dev dependencies を追加してよいか
• phpstan.neon を変更してよいか
• baseline を再生成してよいか

これらの許可条件によって、wp-phpstan が code fix、configuration fix、dependency fix のどれを優先すべきかが変わります。

抽象的な目標より具体的な入力を優先する

入力が具体的であるほど、出力も良くなります。たとえば次の情報を含めてください。

• 現在の PHPStan level
• 解析対象の directories
• CI に WordPress core が含まれているかどうか
• missing-symbol エラーを出している具体的な plugin または class

これにより、wp-phpstan スキルは Backend Development 作業に合ったインストールと利用の道筋を提案しやすくなり、汎用的な PHPStan チェックリストで済ませなくてよくなります。

config から annotations へ順に詰める

よい wp-phpstan guide は、通常次の順序で進みます。

1. stubs と discovery を確認する
2. excludes と ignores を絞る
3. WordPress-specific な動的型を注釈する
4. 受け入れた legacy debt に限って baseline を更新する

この順序なら、WordPress の動的モデルが推論を妨げる部分では誤検知を減らしつつ、新しい問題はしっかり検出できるだけの厳しさを保てます。