WordPress プラグイン自作の方法｜最小構成のファイルと有効化・停止・削除の書き方

結論

WordPress のプラグイン自作は、wp-content/plugins/ にフォルダを1つ作り、その中の PHP ファイルに「Plugin Name」を含むヘッダーコメントを書くだけで始められます。これで管理画面の「プラグイン」一覧に表示され、有効化できるようになります。

実用に耐える最小構成は次の4点です。

  1. フォルダとメインファイル（my-plugin/my-plugin.php）にヘッダーコメント
  2. ファイル先頭で ABSPATH を確認し、直接アクセスを防ぐ
  3. 関数・オプション名に独自の接頭辞を付ける
  4. 必要に応じて、有効化（register_activation_hook()）・停止（register_deactivation_hook()）・削除（uninstall.php）の処理を用意する

テーマの functions.php に書く方法との違いは、テーマを変えても機能が残ることです。サイトの見た目に関係しない機能（お知らせの表示、独自の投稿タイプ、外部サービス連携など）はプラグインにしておくと、テーマの入れ替えで機能が消える事故を防げます。

原因・仕組み

WordPress は wp-content/plugins/ 以下のファイルのヘッダーコメントを読み、プラグインとして認識します。Plugin Handbook の Header Requirements によると、必須なのは Plugin Name だけで、ほかに Description、Version、Requires at least（最小の WordPress 版）、Requires PHP（最小の PHP 版）、Author、License、Text Domain、Update URI、Requires Plugins（依存プラグインのスラッグ）などを書けます。Version は PHP の version_compare() で比べられるため、新しい版が大きくなる形式で付けます。

また、Plugin Basics は「ヘッダーコメントを持つファイルはフォルダ内に1つだけにする」としています。

有効化・停止・削除のタイミングで動く処理は役割が分かれています。

タイミング 書き方 主な用途（Handbook の説明）
有効化 register_activation_hook() 初期値の保存、パーマリンクの更新など
停止 register_deactivation_hook() キャッシュなど一時データの削除
削除 uninstall.php または register_uninstall_hook() オプションや独自テーブルなど、データの完全な削除

手順（サンプルコード）

管理画面に一行のお知らせを出すだけのプラグインです。wp-content/plugins/ks-hello-notice/ks-hello-notice.php として保存します。

<?php
/*
 * Plugin Name:       KS Hello Notice
 * Description:       管理画面に一行のお知らせを出すサンプル。
 * Version:           1.0.0
 * Requires at least: 6.5
 * Requires PHP:      7.4
 * Author:            Example
 * License:           GPL-2.0-or-later
 * Text Domain:       ks-hello-notice
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit; // WordPress 経由以外での直接アクセスを止める
}

function ks_hello_notice_activate() {
    add_option( 'ks_hello_notice_message', 'こんにちは' );
}
register_activation_hook( __FILE__, 'ks_hello_notice_activate' );

function ks_hello_notice_deactivate() {
    delete_transient( 'ks_hello_notice_cache' );
}
register_deactivation_hook( __FILE__, 'ks_hello_notice_deactivate' );

function ks_hello_notice_render() {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    $msg = get_option( 'ks_hello_notice_message', '' );
    printf( '<div class="notice notice-info"><p>%s</p></div>', esc_html( $msg ) );
}
add_action( 'admin_notices', 'ks_hello_notice_render' );

同じフォルダに uninstall.php を置くと、管理画面で「削除」したときに実行されます。

<?php
if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    exit;
}
delete_option( 'ks_hello_notice_message' );

ファイルが増えてきたら、Best Practices の例のように includes/・admin/・public/・languages/ へ分け、メインファイルから require_once plugin_dir_path( __FILE__ ) . 'includes/....php'; で読み込みます。

動作確認（検証環境と結果）

WordPress 7.1.2（ja）／PHP 8.2.12 の CLI 検証環境で、上の2ファイルを実際に wp-content/plugins/ に作り、get_plugin_data()・activate_plugin()・deactivate_plugins()・uninstall_plugin() を順に呼びました（php run.php wl2_plugin.php、ログは tests/plugin-create-minimum-structure.md）。

Name=KS Hello Notice Version=1.0.0 RequiresWP=6.5 RequiresPHP=7.4 TextDomain=ks-hello-notice
listed=yes
activate=NULL
is_active=true
option=こんにちは
notice=<div class="notice notice-info"><p>こんにちは</p></div>
after deactivate is_active=false
has_uninstall=true
after uninstall option=false
cleanup=true
  • ヘッダーの各項目が読み取られ、get_plugins() の一覧に載りました。
  • 有効化で有効化フックが動き、オプションが保存されました。admin_notices を発火させると、エスケープ済みのお知らせが出力されました。
  • 停止後は無効になり、uninstall.php があるため削除可能と判定され、削除処理でオプションが消えました。最後にフォルダごと片付けています。
  • ブラウザでの管理画面表示はこの環境では確認していません（関数を直接呼んで確認）。

WordPress プラグイン自作の方法の注意点

  • 関数名・オプション名には、wp_ などの WordPress 本体の接頭辞を避け、4〜5文字以上の独自の接頭辞を付けます（Best Practices の推奨）。名前が他のプラグインとぶつかると、致命的エラーで画面が真っ白になります。
  • uninstall.php では必ず WP_UNINSTALL_PLUGIN を確認します。なお Handbook によると、register_uninstall_hook() 経由のときはこの定数は定義されません。
  • 停止フックでユーザーのデータを消さないでください。停止は一時的なことが多く、設定まで消すと再有効化のときに困ります。
  • 画面に出す値はエスケープし、保存や変更を伴う処理には権限確認（current_user_can()）と nonce を入れます。

WordPress プラグイン自作の方法でよくあるミス

  • ヘッダーを書いたファイルをフォルダの中に2つ作り、一覧に二重に出る。
  • register_activation_hook() を init などのフックの中で呼び、有効化時に登録されていない。メインファイルの直下で呼びます。
  • 有効化フックで出力（echo）をして、「予期しない出力が発生しました」の警告を出す。
  • 接頭辞なしの function notice() のような名前を付け、別のプラグインと衝突する。

WordPress プラグイン自作の方法のチェックリスト

  • [ ] wp-content/plugins/<フォルダ>/<同名>.php に Plugin Name を書いた
  • [ ] 先頭で ABSPATH を確認している
  • [ ] 関数・オプション・定数に独自の接頭辞を付けた
  • [ ] 出力はエスケープ、変更処理は権限と nonce を確認している
  • [ ] 停止で消すのは一時データだけにした
  • [ ] 削除時の処理（uninstall.php）を用意した
  • [ ] Requires at least / Requires PHP を実際に動く版で書いた

WordPress プラグイン自作の方法のFAQ（よくある質問）

Q. functions.php に書くのとプラグインにするのは、どう使い分けますか。
A. 見た目（テーマ）に依存する処理は functions.php、テーマを変えても残したい機能はプラグインにするのが目安です。

Q. 1ファイルだけのプラグインも作れますか。
A. 作れます。wp-content/plugins/ 直下に1ファイルで置いても認識されますが、後からファイルが増えるのでフォルダにしておくのがおすすめです。

Q. 必ず読み込ませたい場合は。
A. wp-content/mu-plugins/ に置くと、有効化操作なしで常に読み込まれます（停止できない点に注意）。

筆者の見解（WordPress プラグイン自作の方法）

プラグイン自作の入口は意外なほど小さく、ヘッダー1つで動き始めます。だからこそ、私見では最初の1本から「直接アクセス防止」「接頭辞」「エスケープと権限確認」「削除時の後片付け」の4つを型として書いておくことが大切だと考えます。小さなお知らせ表示でも、この型を守っておけば、機能が増えたときにそのまま育てられます。

WordPress プラグイン自作の方法の関連項目

出典（一次情報）

タイトルとURLをコピーしました