wp-phpstan

wp-phpstan 技能概覽

wp-phpstan 是在 WordPress 程式碼庫中把 PHPStan 用好，而不只是「能跑起來」時該用的技能。它特別適合外掛、佈景主題與網站開發者，目標是讓靜態分析更乾淨、降低誤判，並為已存在問題的舊程式碼提供一條實際可行的處理路徑。

它的核心工作是設定與修復：接上 phpstan.neon、處理 baseline、載入 WordPress stubs，以及在 PHPStan 無法推斷執行期行為時，補上懂 WordPress 的型別註解。

wp-phpstan 最適合的使用情境

當你需要以下事情時，請使用 wp-phpstan 技能：

• 在 WordPress repo 中設定或更新 PHPStan
• 降低因缺少 WordPress core symbols 而產生的錯誤
• 管理 phpstan-baseline.neon，同時不把新的 regression 蓋掉
• 修正 WordPress 的動態模式，例如 hooks、REST requests、query results
• 處理可選的第三方外掛類別，例如 WooCommerce 或 ACF

wp-phpstan 為什麼不一樣

一般的 PHPStan 提示，常常會漏掉 WordPress 才有的限制：執行時才載入的 classes、hook callbacks、外掛相依性，以及與實際站點不一致的分析環境。wp-phpstan 的價值在於它會先處理這些邊界情況，尤其是 stub 載入與有針對性的忽略規則。

什麼情況下不適合用

如果你只是想快速了解一條 PHPStan 指令，這個技能可能超出你的需要。它最有價值的情境，是當分析品質重要到設定選擇、baseline 政策與型別提示都會影響結果時。

如何使用 wp-phpstan 技能

安裝並驗證技能

若要 wp-phpstan install，請從 WordPress agent skills repo 加入這個技能：

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

安裝完成後，請先讀 SKILL.md，再讀支援參考文件與檢查腳本。這個 repo 的結構，就是為了回答最影響採用結果的問題：PHPStan 看得到什麼、忽略了什麼，以及哪些地方應該用型別標註而不是直接 suppress。

提供給技能正確的輸入

在要求修正之前，wp-phpstan 技能在有專案脈絡時表現最好。建議一開始就提供：

• wp-project-triage 的輸出
• 是否可以變更 Composer dev dependencies
• 是否允許更新 baseline
• 你想修改的具體 PHPStan 錯誤或 config 檔案

較弱的提示詞是：
「幫我修 PHPStan 在我的 WordPress 外掛裡的問題。」

較好的提示詞是：
「使用 wp-phpstan 檢查我外掛目前的 PHPStan 設定，確認是否已載入 szepeviktor/phpstan-wordpress，並提出能修正未知 WordPress functions、但不使用大範圍忽略的最小 config 變更。只有既有的舊問題才允許改 baseline。」

建議的工作流程與檔案

若要實際掌握 wp-phpstan 的使用方式，請依照 repo 自己的決策路徑：

1. 用 scripts/phpstan_inspect.mjs 檢查設定
2. 查看主要 config 與 baseline 檔案
3. 閱讀 references/configuration.md
4. 閱讀 references/third-party-classes.md
5. 當問題是型別推斷而不是設定時，使用 references/wordpress-annotations.md

如果你想最快得到好結果，建議先預覽這些檔案：

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

實用的提示詞格式

好的提示詞會清楚告訴技能：哪些東西不能動、哪些可以調整，以及你要什麼輸出。例如：

• 「幫我檢查 WordPress 外掛的 phpstan.neon，並告訴我應該加 stubs、收緊 ignoreErrors，還是更新 baseline。」
• 「把這段 REST controller 註解改寫成 PHPStan 能理解 request shape 的格式。」
• 「我的分析環境沒有 WooCommerce；請針對這些缺少的 classes 提出範圍很窄的 stub/ignore 策略。」

這種程度的細節，能幫 wp-phpstan 在 config 變更、註解補強與依賴調整之間做出正確選擇。

wp-phpstan 技能常見問題

wp-phpstan 只適合 WordPress 外掛嗎？

不是。wp-phpstan 也很適合佈景主題，以及有自訂程式碼的 WordPress 網站。只要 PHPStan 需要理解 WordPress 的執行期行為，這個技能就很有用。

我需要先安裝 Composer 和 PHPStan 嗎？

需要。這個技能預設你走的是以 Composer 為基礎的 PHPStan 工作流程。如果你的 repo 沒有用 Composer，或 PHPStan 不是工具鏈的一部分，這個技能就不太適合。

這比自己寫一個自訂提示詞更好嗎？

通常是，前提是你重視可重複的設定決策。自訂提示詞可能可以解掉單一錯誤，但 wp-phpstan 在 baseline、stubs 與 WordPress 專屬型別處理上，會給你更完整的工作流程。

什麼時候應該避免大範圍忽略？

當某個 class 或 function 其實是因為缺少 stub、autoload 問題，或分析環境不一致才被判定不存在時，就應避免大範圍忽略。只有在確認相依路徑是真實存在、而且無法乾淨修正之後，才使用有針對性的忽略。

如何改善 wp-phpstan 技能

先指出真正的 PHPStan 失敗模式

wp-phpstan 要得到最好的結果，關鍵是先辨識失敗類型，再要求修正：

• 不認得 WordPress core functions → stubs 或 config
• 舊程式碼雜訊太多 → baseline 工作流程
• 動態 request data → @phpstan-param 或可重用的 type aliases
• 可選外掛 API → 有針對性的 stubs 或窄範圍忽略

如果你只是貼一串錯誤清單，技能很可能只是在優化症狀，而不是處理根因。

明確交代分析邊界

把技能可以改哪些東西講清楚，結果會更好。請明確說明：

• 能不能改 composer.json？
• 能不能新增 dev dependencies？
• 能不能改 phpstan.neon？
• 能不能重新產生 baseline？

這些權限會決定 wp-phpstan 應該優先做程式修正、設定修正，還是依賴修正。

盡量提供具體輸入，不要只講抽象目標

輸入越具體，輸出通常越準。建議包含：

• 目前的 PHPStan level
• 你分析的目錄
• CI 裡是否有 WordPress core
• 是哪個 plugin 或 class 在造成 missing-symbol errors

這樣 wp-phpstan 才能為 Backend Development 工作建議正確的安裝與使用路徑，而不是只給你一份泛用的 PHPStan 檢查清單。

依照 config 到 annotations 的順序迭代

一份好的 wp-phpstan guide 通常會照這個順序走：

1. 先確認 stubs 與 discovery 是否正常
2. 收窄 excludes 與 ignores
3. 為 WordPress 專屬的動態型別補上註解
4. 只有在已接受的舊債範圍內才更新 baseline

這個順序能讓分析保持足夠嚴格，持續抓出新問題，同時在 WordPress 的動態模型讓推斷失效時，降低誤判。