アクションは、フックの2つのタイプのうちの1つです。WordPress コア、プラグイン、テーマの実行中の特定のポイントで関数を作動させる方法を提供します。アクション用のコールバック関数は、呼び出したアクションフックに何も返しません。フィルターと対になるものです。ここでアクションとフィルターの違いを再確認しておきましょう。
アクションの追加
アクション追加のプロセスには、2つのステップがあります:
コールバック関数の作成
まず、コールバック関数 を作ります。この関数は、フックされたアクションが実行されたときに作動します。
コールバック関数は通常の関数と同じです: 接頭辞をつけ、functions.php または呼び出し可能な場所に記述します。この関数が受け取るべきパラメータは、フック先のアクションによって定義されます。ほとんどのフックはきちんと定義されているので、選択したアクションがどのパラメータを関数に渡すのか、フックのドキュメントを確認してください。
コールバック関数の割り当て (フック)
次に、コールバック関数をアクションに追加します。これは hooking と呼ばれ、アクションが実行されたときにコールバック関数を作動させるようにアクションに指示します。
コールバック関数の準備ができたら、add_action() を使って、選択したアクションにフックします。最低限、add_action() は2つのパラメータを必要とします:
string $hook_nameは、フックするアクションの名前で、callable $callbackは、コールバック関数の名前です。
以下の例では、init フックが実行されると wporg_callback() が作動します:
function wporg_callback() {
// do something
}
add_action( 'init', 'wporg_callback' );
利用可能なフックのリストについては、フックの章を参照してください。
経験を積むにつれ、WordPress コアのソースコードに目を通すことで、最も適切なフックを見つけることができます。
追加パラメータ
add_action() は2つの追加パラメータを受け取ることができ、int $priority はコールバック関数に与える優先度、int $accepted_args はコールバック関数に渡される引数の数です。
優先順位
多数のコールバック関数を、単一のアクションにフックできます。たとえば、init フックはよく使われます。このとき他のコールバック関数の前、または後、ときには他のコールバック関数がまだフックされていないタイミングで、コールバック関数の実行を保証したい場合があります。
WordPress は、コールバック関数の実行順序を2つのことにもとづいて決定します: 1つ目は、手動で「優先度」を設定する方法です。これは add_action() の第三引数を使って行います。
優先順位に関する重要な事実をいくつか紹介しましょう:
- 優先度は、正の整数で、通常は1から20の間です。
- (手動で
priority値を指定しなかった場合に割り当てられる) デフォルトの優先度は10です。 - 優先度の理論的な上限はありませんが、現実的な上限は100です。
優先度11の関数は、優先度10の関数の「後」に実行され、優先度9の関数は、優先度10の関数の「前」に実行されます。
コールバック関数の順番が決定される2つ目の方法は、単純に 同じ優先度同士 で登録された順番です。つまり、2つのコールバック関数が同じフックに同じ優先度で登録されている場合、フックに登録された順番に実行されます。
たとえば、以下のコールバック関数はすべて init フックに登録されていますが、優先順位は異なります:
add_action( 'init', 'wporg_callback_run_me_late', 11 );
add_action( 'init', 'wporg_callback_run_me_normal' );
add_action( 'init', 'wporg_callback_run_me_early', 9 );
add_action( 'init', 'wporg_callback_run_me_later', 11 );
上記の例では:
- 最初に実行される関数は、優先順位は9ですので、
wporg_callback_run_me_early()となります。 - 次は、優先順位が設定されていないので、優先順位は10になる
wporg_callback_run_me_normal()です。 - 次が、優先順位が11に手動で設定されている
wporg_callback_run_me_late()です。 - 最後に
wporg_callback_run_me_later()が作動します: これも優先順位は11ですが、wporg_callback_run_me_late()の後にフックされました。
引数の数
コールバック関数が、フックされているアクションに関連する追加データを受け取ることが望ましい場合があります。
たとえば、WordPress が投稿を保存して save_post フックを実行すると、コールバック関数に2つのパラメータが渡されます: 保存される投稿の ID と、投稿オブジェクト自身です:
do_action( 'save_post', $post->ID, $post );
save_post フックにコールバック関数が登録されると、この2つのパラメータを受け取るように指定できます。(この例では) 4番目の引数として 2 を指定することで、add_action にそれらを受け取るように指示することで行います。:
add_action( 'save_post', 'wporg_custom', 10, 2 );
コールバック関数でこれらのパラメータを実際に受け取るには、コールバック関数が受け取るパラメータを次のように修正します:
function wporg_custom( $post_id, $post ) {
// do something
}