小粋空間  -  a cheap joke and a play on words site

WordPressのadd_filterとapply_filtersのまとめ

WordPressのadd_filterとapply_filtersの使い方についてまとめました。

１．はじめに

WordPressで取得したデータを加工するときにadd_filterという関数を利用することがあると思います。

この関数の使い方を一度覚えてしまえばほぼ同じフォーマットで色々応用できるのですが、個人的にはapply_filtersとの関係がよくわかっていませんでした。

ということで、add_filterおよびapply_filtersの使い方とその仕組みについてまとめてみました。

２．add_filterとは

add_filterは、テンプレートに追加する「独自のフィルタ」です。

たとえば本文を取得するthe_content()にフィルタを追加する場合、function.phpに次のように記述します。

add_filter('the_content', 'hoge');

第1パラメータが独自フィルタを追加したいタグ名（あるいはフィルタ名）、第2パラメータが起動する独自フィルタ名（＝関数名）です。

よって第2パラメータの関数hogeもfunction.phpに実装します。

function hoge($content) {
    return 'Hello!!' . $content;
}

こう書いておけば、テンプレートにthe_content()を記述したときに、本文の先頭に「Hello!!」が付与されます。

独自関数の引数$contentは、後述するapply_filtersの実装に依存します。

つまり、add_filterを実装する人が引数を自由に決めることはできません。

言い換えると、引数も自由に決めたい場合はapply_filtersも実装する必要がありますが、このエントリーでは割愛します。

なお、公式サイトのadd_filterの解説には「指定したフィルターフックに、関数をフックします。」とありますが、第1パラメータがフィルターフック、第2パラメータが関数に該当します。

add_filter( フィルターフック, 関数名 );

３．apply_filtersとは

apply_filtersはadd_filterを呼び出すための関数です。

公式サイトのapply_filtersの解説には「フィルターフックに追加された関数を呼び出します。」とあります。

つまりadd_filterでフィルターフックに追加した関数を呼び出す、という意味です。

apply_filtersはデフォルトでWordPressに実装されているものが数多くあります。

さきほどのthe_content()のadd_filterに対応するapply_filtersは、次の赤色部分になります。

function the_content( $more_link_text = null, $strip_teaser = false) {
    $content = get_the_content( $more_link_text, $strip_teaser );
    $content = apply_filters( 'the_content', $content );
    $content = str_replace( ']]>', ']]>', $content );
    echo $content;
}

apply_filtersの第1パラメータにタグ名、第2パラメータ以降にadd_filterに引き継ぐデータを記述します。

４．add_filterで追加した関数が呼ばれる仕組み

ここからが本題で、the_content()を例にadd_filterで追加した関数がapply_filtersを介して起動される仕組みをシーケンス図で示します。

まず、テンプレートにthe_content()を記述した場合の本文取得のシーケンスは次のとおりです。

テンプレートが読み込まれたタイミングでpost-template.phpに実装されたthe_content()が起動し、本文を取得・返却します。

上記のシーケンスにadd_filterとapply_filtersのシーケンスを追加すると、次のようになります。

（クリックで拡大）

まず、一番右側にあるfunction.phpに実装したadd_filter()がテンプレートが読み込まれるよりも先に起動し、wp-includes/plugin.phpのadd_filter()が動作します。

add_filter()では、第1パラメータに記載されたタグ名（またはフィルタ名、フィルターフック）と第2パラメータの関数（ここではhoge）をリストに登録します。

リストはタグ名別にさらに配列になっていて、配列の要素に関数名が保持されているイメージです。

そしてテンプレートに記述したthe_content()が動作したタイミングでthe_content()に実装されたwp-includes/plugin.phpのapply_filters()が起動します。

apply_filters()では、第1パラメータに設定されたタグ名でリストを検索し、リストに関数が設定されている場合、PHPのcall_user_func_array()を使ってhoge()という関数を起動します。

hoge()では本文を加工・返却し、最終的にテンプレートに加工した本文が返却されます。

以上が、the_content()で取得した本文が加工されるという仕組みになります。

ざっくりとしか説明していない部分もあるので予めご容赦ください。また認識誤り等ありましたらどこかでつぶやいてください。

参考までに、もう少し抽象化したシーケンスも掲載しておきます。

（クリックで拡大）

５．add_filterの起動順序

apply_filters()の名称が複数形になっていることから、一つのフィルタに複数の関数をフックすることができることがお分かりになると思います。

で、一つのフィルタに複数の関数をフックしており、その順番を規定したい場合は、add_filterの第3パラメータに起動順序を指定します。

add_filter('the_content', 'hoge', 3);

デフォルトは10です。

値が小さいほど早く実行され、同じ値が存在する場合は追加された順に実行されます。