WordPressのregister_activation_hook()は初期設定をプラグイン有効化時だけ実行する

WordPressプラグインの初期設定は、通常のページ表示処理へ混ぜず、register_activation_hook()で有効化時の処理として登録します。初期optionの追加など、一度準備すれば通常リクエストで繰り返す必要がない処理を分けられます。

ただし、有効化処理はプラグインの生涯で一回だけとは限りません。停止したプラグインを再び有効化すれば、同じcallbackが実行されます。既存データを勝手に上書きしない処理にしておく必要があります。

register_activation_hook()はメインプラグインファイルで登録する

WordPress 3.9.1のPlugin APIでは、register_activation_hook()がメインプラグインファイルのbasenameから有効化用のaction名を作り、指定したcallbackを登録します。

次は、プラグインの初期optionを追加する説明用の例です。関数名、option名、値は仮のものです。

function satolab_example_activate() {
    add_option( 'satolab_example_version', '1.0' );
}

register_activation_hook( __FILE__, 'satolab_example_activate' );

このコードは、プラグインのメインファイルへ置きます。別ファイルへ処理を分ける場合も、第一引数にはメインプラグインファイルのパスが必要です。分割先の__FILE__をそのまま渡すと、WordPressが有効化するプラグインのbasenameと一致しません。

register_activation_hook()の呼出し自体は、メインファイルが読み込まれたときにcallbackを登録する処理です。登録したcallbackが実行されるのは、そのプラグインを有効化するときです。

plugins_loadedやinitの中では登録しない

有効化hookの登録をplugins_loadedやinitのcallback内へ入れると、有効化処理へ間に合いません。有効化のために新しいプラグインファイルが読み込まれる時点では、plugins_loadedはすでに実行されています。

// 有効化hookの登録場所としては使わない
function satolab_example_late_registration() {
    register_activation_hook( __FILE__, 'satolab_example_activate' );
}
add_action( 'init', 'satolab_example_late_registration' );

通常リクエストで使う処理をinitなどへ登録することと、有効化callbackを登録することは別です。前者はページ表示や管理操作のたびに必要な機能、後者はプラグインを使い始めるための準備を担当します。

処理を一つの関数へまとめるかではなく、いつ実行する責任があるかで分けます。

再有効化しても既存設定を上書きしない

有効化callbackは、停止後の再有効化でも実行されます。初期値を入れる目的なら、既存optionを上書きするupdate_option()ではなく、optionがない場合だけ追加するadd_option()を選べます。

WordPress 3.9.1のadd_option()は、同じoptionがすでに存在する場合、追加せずfalseを返します。上の例なら、運用中に変更した'satolab_example_version'を再有効化のたびに初期値へ戻しません。

ただし、optionのversionを更新処理にも使う設計なら、初期追加だけでは足りません。既存versionを読み、どの変更をどの順で適用するかは、有効化とは別に設計します。add_option()へ変えれば、すべての更新処理が完成するわけではありません。

初期化する項目ごとに、次の三つを決めます。

有効化時に作る責任と、削除時に片付ける責任を対にしておけば、停止や削除の判断もしやすくなります。

有効化callbackから画面へ出力しない

WordPressの有効化処理は、プラグインファイルを読み込み、登録された有効化actionを実行します。WordPress 3.9.1のactivate_plugin()は処理中の出力を捕捉し、予期しない出力があればerrorとして扱います。

有効化callbackでは、次の出力を行いません。

• echoやprintで説明文を表示する
• PHP開始タグの前や終了タグの後へ空白を出す
• 初期化の途中結果をHTMLとして表示する
• debugging用の文字列を利用者へ直接出す

初期化結果を確認する必要がある場合は、保存したoptionや作成対象を管理画面から確認できる手順を別に用意します。画面へ何か表示したいという目的を、有効化callbackへ混ぜません。

有効化と通常リクエストを別々に確認する

実装後は、有効化画面だけでなく、再有効化と通常のページ表示を分けて試します。

1. 未導入の状態で有効化し、必要な初期値が追加されるか確認する。
2. 初期値を運用用の値へ変更する。
3. プラグインを停止し、再び有効化して、既存値が上書きされないか確認する。
4. 公開画面と管理画面を開き、有効化専用の処理が毎回走っていないか確認する。
5. PHPの出力とerror logを確認する。

プラグインを停止すると機能の実行は止まりますが、optionが自動で消えるとは限りません。再有効化で同じ設定を使うなら残す設計にできます。削除時に消すかどうかは、利用者が保管を望むデータか、再導入に必要かを決めてから実装します。

最初の一手は、プラグイン内の処理を「有効化時の準備」と「通常リクエストで必要な処理」に分けることです。初期optionが一つあるなら、既存値を残す条件を決めてregister_activation_hook()へ移します。