register_activation_hook() の使い方｜説明・引数・注意点

説明

基本構文

register_activation_hook( string $file, callable $callback ): void

引数

• $file：プラグインのメインファイルのパス（通常 __FILE__）
• $callback：有効化時に実行する関数

戻り値

戻り値はありません。

使い方（サンプル）

register_activation_hook( __FILE__, 'myplugin_activate' );
function myplugin_activate() {
	add_option( 'myplugin_version', '1.0' );
}

注意点

• プラグインのメインファイルの最上位（フック内ではなく直接）で呼び出します。
• アップデート時には実行されません。
• マルチサイトでは、ネットワーク有効化時の扱いに注意が必要です。

実務での使いどころ

• プラグインを、有効化したときに、一度だけ行う処理（テーブルの作成、初期設定、リライトルールの更新）を、書くとき。

よくあるミスと対処

• 第1引数に、メインのプラグインファイルの __FILE__ を渡していない。別のファイルの __FILE__ では、動かない。
• フックの中や、関数の中で呼んでいる。ファイルの直下（最上位）で、呼ぶ。
• プラグインの更新では、呼ばれない。更新時の処理は、別に用意する。
• カスタム投稿タイプの登録の前に、flush_rewrite_rules() を呼んでいる。
• テーマには使えない。テーマには、after_switch_theme フックを使う。

NG例

add_action( 'init', function () {
	register_activation_hook( __FILE__, 'my_activate' ); // フックの中では、動かない
} );

OK例

register_activation_hook( __FILE__, 'my_activate' );
function my_activate() {
	my_register_post_types();
	flush_rewrite_rules();
}

使い分け早見表

関連項目

register_deactivation_hook()、register_uninstall_hook()、flush_rewrite_rules()

公式リファレンス：register_activation_hook() | Function | WordPress Developer Resources