wp-plugin-development

WP 外掛開發

使用時機

當外掛開發工作涉及以下項目時使用此技能：

• 建立或重構外掛結構（啟動檔、引入、命名空間/類別）
• 新增掛鉤/動作/過濾器
• 啟用/停用/移除行為與資料遷移
• 新增設定頁面 / 選項 / 管理後台 UI（設定 API）
• 安全性修正（nonce、權限、清理/跳脫、SQL 安全）
• 打包發佈（建置產物、readme、素材）

所需輸入

• 儲存庫根目錄 + 目標外掛（若已知，提供外掛主檔案路徑）。
• 此外掛運作環境：單站點 vs 多站點；若適用，遵循 WP.com 慣例。
• 目標 WordPress + PHP 版本（影響可用 API 及 $wpdb->prepare() 中的佔位符支援）。

程序

0) 分類與定位外掛進入點

1. 執行分類：
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. 偵測外掛標頭（確定性掃描）：
   • node skills/wp-plugin-development/scripts/detect_plugins.mjs

若為完整站點儲存庫，在修改程式碼前，請選定 wp-content/plugins/ 或 mu-plugins/ 下的特定外掛。

1) 遵循可預測的架構

指引：

• 保持單一啟動檔（包含標頭的主外掛檔案）。
• 避免在檔案載入時產生大量副作用；應在掛鉤上載入。
• 偏好使用專用的載入器/類別來註冊掛鉤。
• 將僅限管理員的程式碼放在 is_admin()（或管理掛鉤）之後，以減少前台負擔。

請參閱：

• references/structure.md

2) 掛鉤與生命週期（啟用/停用/移除）

啟用掛鉤較為脆弱；請遵循以下防護措施：

• 在最上層註冊啟用/停用掛鉤，而非在其他掛鉤內部
• 僅在必要時且註冊自訂文章類型/規則後才清除重寫規則
• 移除應明確且安全（uninstall.php 或 register_uninstall_hook）

請參閱：

• references/lifecycle.md

3) 設定與管理後台 UI（設定 API）

偏好使用設定 API 處理選項：

• register_setting()、add_settings_section()、add_settings_field()
• 透過 sanitize_callback 進行清理

請參閱：

• references/settings-api.md

4) 安全性基準（務必執行）

在發佈前：

• 及早驗證/清理輸入；延後跳脫輸出。
• 使用 nonce 防止 CSRF，並搭配權限檢查進行授權。
• 避免直接信任 $_POST / $_GET；使用 wp_unslash() 及特定鍵值。
• 使用 $wpdb->prepare() 處理 SQL；避免使用字串串接建構 SQL。

請參閱：

• references/security.md

5) 資料儲存、排程、遷移（若需要）

• 小型設定偏好使用選項；僅在必要時使用自訂資料表。
• 對於排程任務，確保冪等性，並提供手動執行路徑（WP-CLI 或管理後台）。
• 對於結構變更，撰寫升級程式並儲存結構版本。

請參閱：

• references/data-and-cron.md

驗證

• 外掛啟用時無致命錯誤/通知。
• 設定能正確儲存與讀取（強制執行權限 + nonce）。
• 移除時刪除預期資料（且僅刪除這些資料）。
• 執行儲存庫的 lint/測試（若有 PHPUnit/PHPCS）以及任何 JS 建置步驟（若外掛包含前端素材）。

失敗模式 / 除錯

• 啟用掛鉤未觸發：
  • 掛鉤註冊不正確（不在主檔案範圍內）、主檔案路徑錯誤、或外掛為網路啟用
• 設定未儲存：
  • 設定未註冊、選項群組錯誤、缺少權限、nonce 驗證失敗
• 安全性回歸：
  • 有 nonce 但缺少權限檢查；或已清理的輸入未在輸出時跳脫

請參閱：

• references/debugging.md

升級處理

如需標準細節，請查閱外掛手冊與安全指南，再自行設計模式。