Wordpressのdo_actionの使い方

▶

編集

この記事の要点

do_action() は、指定したフック名（アクションフック）に登録された関数をまとめて実行する WordPress の関数
関数の登録は add_action( フック名, 関数, 優先度, 引数の数 ) で行う
書式: do_action( $hook_name, ...$args )。引数はいくつでも渡せる
2 個以上の引数を受け取るには add_action の第 4 引数（受け取る引数の数）を指定する。既定は 1
値を加工して返したいときは do_action ではなく apply_filters()（フィルターフック）を使う
テーマやプラグインに独自のフックを用意すると、元のファイルを書き換えずに処理を追加できる

本稿では WordPress の do_action 関数について、仕組み・書き方・よくある失敗を説明します。

do_action とは

do_action 関数を使用すると、WordPress の既存の関数や、自分で定義した関数を呼び出すことができます。

ただし、1 つの関数を名前で直接呼び出すのではありません。あらかじめ関数に「フック名」（旧称タグ）を付けて登録しておき、do_action でそのフック名を指定すると、そのフック名で登録されたすべての関数が一度に呼び出されます。これを WordPress では「アクションフック」と呼びます。

この仕組みのおかげで、呼び出す側（WordPress 本体やテーマ）は「ここで何が実行されるか」を知らなくてよく、追加したい側（プラグインや子テーマ）は元のコードを書き換えずに処理を差し込めます。WordPress 本体も、wp_head() の中で do_action( 'wp_head' ) を実行するなど、あちこちでこの関数を使っています。

構文

第 1 引数に呼び出したいフック名を、第 2 引数以降に登録された関数へ渡す引数を指定します。戻り値はありません。

<?php do_action( $hook_name, $arg ); ?>

複数の引数を与える場合は以下のようにします。WordPress 5.3 以降は可変長引数（...$arg）として定義されています。

<?php do_action( $hook_name, $arg_a, $arg_b, $etc ); ?>

関数の登録とフック名の付与

関数を登録するには add_action() を使います。

引数	意味	既定値
$hook_name	フック名	（必須）
$callback	実行する関数（関数名の文字列、無名関数、`[ $obj, 'method' ]` など）	（必須）
$priority	実行順。数字が小さいほど先に実行。同じ値なら登録した順	10
$accepted_args	関数が受け取る引数の数	1

以下は、テーマの functions.php に関数を定義して登録し、呼び出す例です。

// 関数の定義（中身はなんでもいい）
function test_func( $a, $b )
{
    echo $a . " and " . $b;
}

// 関数を登録する
// add_action( $hook_name, $callback, $priority, $accepted_args );
add_action( 'test_tag', 'test_func', 10, 2 );

// 関数を呼び出す
do_action( 'test_tag', "A", "B" );   // A and B と出力される

第 4 引数を省略すると受け取る引数は 1 個になり、test_func に $b が渡らないため、PHP 7.1 以降では ArgumentCountError（引数不足のエラー）になります。引数を 2 個以上受け取る関数は必ず第 4 引数を指定しましょう。

実用例: テーマに独自フックを用意する

テーマのテンプレートに独自のフックを置いておくと、子テーマやプラグインからテンプレートをコピーせずに表示を追加できます。フック名は他と重ならないように、テーマ名などの接頭辞を付けます。

// single.php（親テーマ）
<article>
  <?php do_action( 'mytheme_before_content', get_the_ID() ); ?>
  <?php the_content(); ?>
  <?php do_action( 'mytheme_after_content', get_the_ID() ); ?>
</article>

// 子テーマの functions.php
add_action( 'mytheme_after_content', function ( $post_id ) {
    echo '<p class="note">最終更新: ' . esc_html( get_the_modified_date( '', $post_id ) ) . '</p>';
} );

よく使う WordPress 本体のアクションフック

フック名	実行されるタイミング	主な用途
after_setup_theme	テーマの読み込み直後	テーマ機能（アイキャッチなど）の有効化
init	WordPress の初期化完了後	カスタム投稿タイプの登録
wp_enqueue_scripts	フロント画面の CSS・JS 読み込み時	スタイルやスクリプトの追加
wp_head / wp_footer	head 内 / body 終了直前の出力時	meta タグや計測タグの出力
save_post	投稿の保存時	カスタムフィールドの保存

do_action と apply_filters の違い

フックには「アクション」と「フィルター」の 2 種類があります。do_action は「このタイミングで何かを実行する」ためのもので、登録された関数の戻り値は使われません。値を受け取って加工し、結果を返してほしい場合は apply_filters() と add_filter() を使います。

よくある失敗

add_action が do_action より後に実行されている: フックはその時点で登録済みの関数しか実行しません。プラグインやテーマの読み込み順、フックのタイミングを確認します
引数の数の指定漏れ: 前述のとおり第 4 引数を忘れると 2 個目以降の引数が渡りません
remove_action で外せない: 外すときは登録時と同じフック名・関数・優先度を指定する必要があります。無名関数で登録したものは後から外すのが困難です
フック名の衝突: 汎用的な名前（例: before_content）は他のテーマやプラグインと重なることがあります。接頭辞を付けましょう

確認方法

フックに関数が登録されているかは has_action( 'test_tag' ) で、フックが何回実行されたかは did_action( 'test_tag' ) で確認できます。開発中は Query Monitor などのデバッグ用プラグインを使うと、ページ表示中に実行されたフックと登録関数の一覧を確認できます。

ページ一覧

その他