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 核心樁

szepeviktor/phpstan-wordpress 或 php-stubs/wordpress-stubs 對於大多數 WordPress 外掛/佈景主題儲存庫來說是必要的。缺少時，預期會出現大量關於未知 WordPress 核心函式的錯誤。

• 確認套件已安裝（參閱檢查報告中的 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

驗證

• 使用探索到的命令執行 PHPStan（composer run ... 或 vendor/bin/phpstan analyse）。
• 確認基準線檔案（如有使用）已包含且未意外增長。
• 在變更 ignoreErrors 後重新執行，確保模式未遮蔽無關問題。

失敗模式 / 除錯

• 「找不到類別」：
  • 確認自動載入/樁，或加入狹窄的忽略模式
• 啟用 PHPStan 後出現大量錯誤：
  • 縮小 paths，加入 excludePaths，從較低層級開始，然後逐步提高
• 鉤子 / REST 參數的型別不一致：
  • 加入明確的 PHPDoc（參閱參考資料），而非執行時期防護

升級處理

• 如果型別依賴於你無法確認的第三方外掛 API，請先詢問相依版本或來源，再自行發明型別。
• 如果修復需要新增 Composer 相依套件（樁/擴充套件），請先與使用者確認。