wp-phpstan

WP PHPStan

使用するタイミング

WordPress のコードベースで PHPStan を扱う際に、このスキルを使用します。例：

• phpstan.neon / phpstan.neon.dist の設定または更新
• phpstan-baseline.neon の生成または更新
• WordPress に適した PHPDoc（REST リクエスト、フック、クエリ結果）を使った PHPStan エラーの修正
• サードパーティ製プラグイン／テーマのクラスの安全な取り扱い（スタブ／オートロード／対象を絞った無視設定）

必要な入力

• wp-project-triage の出力（まだ実行していない場合は先に実行してください）
• Composer の開発依存関係（スタブ）の追加・更新が許可されているかどうか。
• このタスクでベースラインの変更が許可されているかどうか。

手順

0) PHPStan のエントリーポイントを特定する（決定的に実行）

1. PHPStan の設定（設定ファイル、ベースライン、スクリプト）を調べます。
   • node skills/wp-phpstan/scripts/phpstan_inspect.mjs

既存の composer スクリプトがある場合は、そちらを優先してください（例：composer run phpstan）。

1) WordPress コアのスタブが読み込まれていることを確認する

ほとんどの WordPress プラグイン／テーマのリポジトリでは、szepeviktor/phpstan-wordpress または php-stubs/wordpress-stubs が事実上必要です。これがない場合、WordPress コア関数が不明であることを示すエラーが大量に発生することが予想されます。

• パッケージがインストールされていることを確認します（inspect レポートの composer.dependencies を参照）。
• PHPStan の設定でスタブが参照されていることを確認します（references/third-party-classes.md を参照）。

2) WordPress プロジェクトに適切な phpstan.neon を用意する

• paths はファーストパーティのコード（プラグイン／テーマのディレクトリ）に絞ります。
• 生成物やベンダーコード（vendor/、node_modules/、ビルド生成物、明示的に解析する場合を除くテスト）を除外します。
• ignoreErrors の項目は範囲を絞り、説明を付けます。

参照先：

• references/configuration.md

3) WordPress 固有の型付けでエラーを修正する（推奨）

エラーを無視するより、型を修正することを優先します。対応が必要になる一般的な WordPress のパターン：

• REST エンドポイント：WP_REST_Request<...> を使ってリクエストパラメーターに型を付けます
• フックコールバック：コールバック引数に正確な @param 型を追加します
• データベースの結果と反復可能な値：クエリ結果に配列シェイプまたはオブジェクトシェイプを使用します
• Action Scheduler：ジョブのコールバックで $args の配列シェイプに型を付けます

参照先：

• references/wordpress-annotations.md

4) サードパーティ製プラグイン／テーマのクラスを扱う（必要な場合のみ）

解析環境に存在しないプラグイン／テーマと連携する場合：

• まず、依存関係が実在することを確認します（インストール済み／必須であること）。
• リポジトリですでに使用されているプラグイン固有のスタブを優先します（一般的な例：php-stubs/woocommerce-stubs、php-stubs/acf-pro-stubs）。
• PHPStan でクラスを解決できない場合は、特定のベンダープレフィックスを対象とする ignoreErrors パターンを追加します。

参照先：

• references/third-party-classes.md

5) ベースラインの管理（ごみ箱ではなく、移行ツールとして使用）

• レガシーコード用のベースラインを一度生成し、その後は徐々に減らします。
• 新たに導入したエラーを「ベースライン化」しないでください。

参照先：

• references/configuration.md

検証

• 特定したコマンド（composer run ... または vendor/bin/phpstan analyse）で PHPStan を実行します。
• ベースラインファイルを使用している場合は、それが読み込まれており、予想外に増えていないことを確認します。
• ignoreErrors を変更した後に再実行し、パターンが無関係な問題まで隠していないことを確認します。

失敗時の対処／デバッグ

• 「Class not found」：
  • オートロード／スタブを確認するか、範囲を絞った無視パターンを追加します
• PHPStan の有効化後にエラー数が大幅に増えた：
  • paths を絞り、excludePaths を追加し、低いレベルから開始して段階的に引き上げます
• フック／REST パラメーター周辺で型に一貫性がない：
  • 実行時のガードではなく、明示的な PHPDoc を追加します（参考資料を参照）

エスカレーション

• 型が確認できないサードパーティ製プラグイン API に依存する場合は、型を推測して作る前に、依存関係のバージョンまたはソースを確認してください。
• 修正に新しい Composer 依存関係（スタブ／拡張機能）の追加が必要な場合は、まずユーザーに確認してください。