アクションとフィルター

WordPressが行う処理の特定箇所(フックポイント)に、ユーザ独自の処理(コールバック)を追加する(フックする)方法を取り上げます。

アクションフックとフィルターフック

フックには、アクションフックとフィルターフックがあります。それぞれ機能的には同じで、特定のタイミングにユーザが作成したメソッドを実行させることができます。

アクションとフィルターに関する処理は、「wordpress/wp-includes/plugin.php」に記述されています。アクションフックポイントを登録するためのメソッドとして、 do_actionメソッド があります。フィルターフックポイントを登録するためのメソッドとして、apply_filtersメソッド があります。それぞれWordPressコアファイル内で次のように利用されています。

// do_action使用例  「wordpress/wp-settings.php内の記述
do_action( 'init' );
 
// apply_filters使用例  「wordpress/wp-includes/formatting.php内の記述」
$excerpt_length = apply_filters( 'excerpt_length', 55 );

次に、それぞれのメソッドの中身を見てみます。

// do_actionメソッド 抜粋 「wordpress/wp-includes/plugin.php内の記述」
function do_action($tag, $arg = '') {
  (省略)
        call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));
  (省略)
}
 
// apply_filtersメソッド 抜粋 「wordpress/wp-includes/plugin.php内の記述」
function apply_filters( $tag, $value ) {
  (省略)
        $value = call_user_func_array($the_['function'], array_slice($args, 1, (int) $the_['accepted_args']));
  (省略)
  return $value;
}

アクションはコールバックの戻り値を利用してませんが、フィルターはコールバックの戻り値を利用していることがわかります。アクションとフィルターの違いをまとめると次のようになります。

項目 アクション フィルター
目的 特定のタイミングでユーザ独自の処理を実行させる。 特定のタイミングで特定の変数を変更させるためにユーザ独自の処理を実行させる。
コールバックの戻り値 なし あり
フックポイントを登録するためのメソッド do_action()
do_action_ref_array()
apply_filters()
apply_filters_ref_array()
フックポイントの一覧確認 WordPress Codex(日本語) WordPress Codex(日本語)
フックするためのメソッド add_action() add_filter()

フィルターフックの例

次のように、example_filterというフィルターフックポイントが登録されているとします。

$value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );

example_filterというフィルターフックポイントでexample_callbackメソッドが実行されるように登録するには次のように指定します。

// 例1. 普通に文字列で関数名を指定する
function example_callback( $string, $arg1, $arg2 ) {
    // (maybe) modify $string
    return $string;
}
add_filter( 'example_filter', 'example_callback', 10, 3 );
 
 
// 例2. オブジェクトのメソッドを指定する
class foo {
    function bar( $string, $arg1, $arg2 ) {
        // (maybe) modify $string
        return $string;
    }
}
$foo = new foo;
add_filter( 'example_filter', array($foo, "bar"), 9, 3 );
  • ※add_filterの引数は次のような役割を持ちます。
    • 第1引数 フックするフィルター名
    • 第2引数 フィルター時に呼び出される関数名
    • 第3引数 優先順位。
    • 第4引数 関数が受け取る引数の数(2つ以上受け取る場合に指定が必要)
  • 同一フックポイントにコールバックを複数登録した場合、優先順位の数値が低い順に実行されます。

上記例では、example_filterというフックポイントで、example_callbackメソッドが実行されます。その際、example_callbackメソッドは3つの引数(‘filter me’, $arg1, $arg2)を受け取ります。