wp-plugin-development

WP プラグイン開発

使用する場面

次のようなプラグイン作業にこのスキルを使用します。

• プラグイン構造の作成またはリファクタリング（ブートストラップ、includes、名前空間／クラス）
• フック／アクション／フィルターの追加
• 有効化／無効化／アンインストール時の処理と移行
• 設定ページ／オプション／管理画面 UI（Settings API）の追加
• セキュリティ修正（nonce、権限、サニタイズ／エスケープ、SQL の安全性）
• リリース用パッケージの作成（ビルド成果物、readme、アセット）

必要な入力

• リポジトリのルートと対象プラグイン（判明している場合はメインファイルのパス）。
• プラグインの実行環境：シングルサイトかマルチサイトか、該当する場合は 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) 予測しやすいアーキテクチャに従う

ガイドライン：

• ブートストラップは 1 つにします（ヘッダーを含むメインのプラグインファイル）。
• ファイルの読み込み時に重い副作用が発生しないようにし、フックで読み込みます。
• フックの登録には専用のローダー／クラスを使用します。
• フロントエンドの負荷を抑えるため、管理画面専用のコードは is_admin()（または管理画面フック）内に置きます。

参照：

• references/structure.md

2) フックとライフサイクル（有効化／無効化／アンインストール）

有効化フックは壊れやすいため、次のガードレールに従います。

• 有効化／無効化フックは、他のフック内ではなくトップレベルで登録します。
• rewrite ルールのフラッシュは必要な場合に限り、CPT／ルールの登録後にのみ実行します。
• アンインストール処理は明示的かつ安全に実装します（uninstall.php または register_uninstall_hook）。

参照：

• references/lifecycle.md

3) 設定と管理画面 UI（Settings API）

オプションには Settings API を優先して使用します。

• register_setting()、add_settings_section()、add_settings_field()
• sanitize_callback によるサニタイズ

参照：

• references/settings-api.md

4) セキュリティの基本（常に実施）

リリース前に、次のことを確認します。

• 入力は早い段階で検証／サニタイズし、出力は直前にエスケープします。
• CSRF 防止には nonce を使用し、認可には権限チェックも実施します。
• $_POST／$_GET を直接信頼せず、wp_unslash() と特定のキーを使用します。
• SQL には $wpdb->prepare() を使用し、文字列連結による SQL の組み立ては避けます。

参照：

• references/security.md

5) データ保存、cron、移行（必要な場合）

• 少量の設定にはオプションを優先し、カスタムテーブルは必要な場合にのみ使用します。
• cron タスクは冪等性を確保し、手動実行の方法（WP-CLI または管理画面）を用意します。
• スキーマを変更する場合は、アップグレード処理を作成し、スキーマのバージョンを保存します。

参照：

• references/data-and-cron.md

検証

• プラグインが致命的エラーや通知なしで有効化されること。
• 設定が正しく保存および読み込みされること（権限と nonce を検証）。
• アンインストール時に、意図したデータだけが削除されること。
• リポジトリの lint／テスト（存在する場合は PHPUnit／PHPCS）と、プラグインにアセットが含まれる場合は JavaScript のビルド手順を実行します。

失敗の原因／デバッグ

• 有効化フックが実行されない：
  • フックの登録方法が誤っている（メインファイルのスコープ外）、メインファイルのパスが誤っている、またはプラグインがネットワーク有効化されている
• 設定が保存されない：
  • 設定が登録されていない、オプショングループが誤っている、権限がない、nonce の検証に失敗している
• セキュリティ上のデグレード：
  • nonce はあるものの権限チェックがない、または入力はサニタイズされているものの出力時にエスケープされていない

参照：

• references/debugging.md

エスカレーション

標準的な詳細については、独自のパターンを作り出す前に Plugin Handbook とセキュリティガイドラインを参照してください。