独自フックの作り方｜do_action と apply_filters の使い分け

結論

独自フックは、事前の登録なしに do_action()（アクション）または apply_filters()（フィルター）を書くだけで作れます。使い分けは次のとおりです。

• 出力や処理を差し込ませたい → do_action( 'myplugin_before_card', $id )
• 値を書き換えさせたい → $html = apply_filters( 'myplugin_card_html', $html, $id )

フック名には、テーマやプラグイン固有の接頭辞を付けます（公式リファレンスでも、プラグインやテーマの slug を前に付ける命名が推奨されています）。引数は、使う側が判断するための材料（投稿IDなど）を渡します。

原因・仕組み

do_action() と apply_filters() は、指定した名前に登録されたコールバックを順に実行するだけの関数です。コールバックが1つもなくてもエラーにならず、apply_filters() は渡した値をそのまま返します。この「何も登録されていなければ素通り」という性質が、拡張ポイントを後から安全に増やせる理由です。

違いは戻り値の扱いです。アクションは戻り値を使わない（do_action は何も返さない）のに対し、フィルターは各コールバックの戻り値が次へ渡され、最終的な値が apply_filters() の戻り値になります。

手順（サンプルコード）

1. 提供側：フックを置く

function mytheme_render_card( $post_id, $title ) {
    do_action( 'mytheme_before_card', $post_id, $title );

    $html = '<div class="card">' . esc_html( $title ) . '</div>';
    $html = apply_filters( 'mytheme_card_html', $html, $post_id );
    echo wp_kses_post( $html ); // フィルターで差し替えられたHTMLも、出力直前に許可タグだけに絞る

    do_action( 'mytheme_after_card', $post_id );
}

デフォルト値を返す設定値も、フィルターで作れます。

function mytheme_per_page() {
    return (int) apply_filters( 'mytheme_per_page', 10 );
}

2. 利用側：フックに処理を登録する

add_action( 'mytheme_before_card', function ( $id, $title ) {
    echo '[before id=' . (int) $id . ']';
}, 10, 2 ); // 引数を2つ受け取るので、第4引数に2

add_filter( 'mytheme_card_html', function ( $html, $id ) {
    return str_replace( 'card', 'card card--' . (int) $id, $html );
}, 10, 2 );

3. 配列・参照を渡す

配列を1つ渡すのは通常の do_action( 'x', $array ) で足ります。参照渡しにしたい場合は do_action_ref_array( 'x', array( &$obj ) ) を使います。なお公式リファレンスには、「中身が1つのオブジェクトだけの配列」を渡すと、コールバックにはその配列ではなくオブジェクトが渡る、という注意書きがあります。

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

WordPress 7.1.2（ja）、PHP 8.2.12 の CLI 環境で実行しました。

• 上記の手順1・2のコードのまま mytheme_render_card( 7, 'Hello <b>' ) を実行した出力：[before id=7]<div class="card card--7">Hello &lt;b&gt;</div>。タイトルはエスケープされ、フィルターでクラスが追加された（執筆時の検証では、mytheme_after_card に [after] を出すコールバックを追加し、カードの後ろに出力されることも確認）。
• 引数を1つしか受け取らない登録（accepted_args 省略）では、第1引数だけが渡された。
• mytheme_per_page() はデフォルトの 10、フィルターが '25' を返すと (int) キャストにより int(25)。
• 配列の引数は array-arg: A1、参照渡しは ref n=2 になった。
• has_action は true、did_action は 1。

ログは testscreate-custom-hook-do-action-apply-filters.md にあります。「配列に入った単一オブジェクト」の挙動は、この環境では検証していません（公式の記載のみに基づきます）。

独自フックの作り方の注意点

• フィルターの戻り値は、(int) などで型を整えてから使うと安全です。使う側が文字列を返すこともあるためです。
• フックに渡す値のエスケープは、出力する側で行う設計に統一します。フィルター後の HTML を echo する場合は、wp_kses_post() などで通す判断を明示します。
• 一度公開したフック名・引数の順番は、変更すると他の人のコードが壊れます。引数は末尾に足すのが基本です。
• フック名は、小文字とアンダースコアで、接頭辞を付けます。init のような汎用名は使いません。

独自フックの作り方でよくあるミス

• apply_filters() の戻り値を受け取らず、結果が反映されない。
• 利用側が add_filter() の第4引数を指定せず、第2引数以降を受け取れない（add_filter() の使い方｜説明・引数・注意点参照）。
• フック名に接頭辞を付けず、他のプラグインと衝突する。
• フィルターの結果を、エスケープせず出力して、脆弱性になる。

独自フックの作り方のチェックリスト

• フック名に、固有の接頭辞を付けたか
• アクションかフィルターか、目的で選んだか
• 渡す引数が、使う側の判断に十分か
• 戻り値の型を整えて使っているか
• 出力前のエスケープ方針を決めたか

独自フックの作り方のFAQ（よくある質問）

Q. フックを作ったことを、利用者にどう伝えますか？
A. ドキュメントに、フック名・引数・戻り値の型・使用例を書くのが一般的です。

Q. 条件によってフック名を変えられますか？
A. 可能です。コアにも {$taxonomy}_add_form のように動的な名前があります。ただし検索しづらくなるため、乱用は避けます。

Q. do_action の代わりに関数を直接呼んでもよいですか？
A. 利用者が差し込む必要がなければ、直接呼んで構いません。拡張点が必要な箇所だけにフックを置きます。

独自フックの作り方の関連項目

• do_action() の使い方｜説明・引数・注意点
• apply_filters() の使い方｜説明・引数・注意点
• add_action() の使い方｜説明・引数・注意点
• add_filter() の使い方｜説明・引数・注意点
• has_action() の使い方｜説明・引数・注意点