前回の記事の続きで今回はフィルターフックについてまとめていきます。

※参考記事
・Web 制作リファレンス（＋α）
・WordPress フィルターフックの使い方を理解する

フィルターフックとは

こちらの記事から抜粋

WordPressの処理の途中で、出力する内容をカスタマイズしたい場合に使われる仕組み

例えばWordPressでブログを設営していたとして、記事タイトルの頭に「■」という記号をつけたくなったとします。
一つ一つに「■」を書き足していくのは非常に手間なので、こういうシーンで役に立つのがフィルターフックというわけです。

「記事タイトルを出力する部分」をフックで引っ掛けてきて、「■を書き足す」と設定しておいたフィルターに通すことで、内容を加工して出力することができます。

フィルターフックの実行方法

工程的にはざっくり以下の通りです。
(1)add_filter関数でフィルターの設定を行う
(2)apply_filters関数を使ってフィルターを実行する

実行したいプログラムの登録と実行を別々の関数で行うという部分はアクションフックと似ています。
.

(1)add_filter関数でフィルターの設定を行う

まずは関数の書き方からです。

<?php add_filter( 
$tag, //第一引数(必須）:フィルターフックの名前（カスタマイズしたい"元の内容"の名前）
$function_to_add, //第二引数(必須）:フィルターが適用されたときに呼び出される関数名
$priority, //第三引数(任意）:関数実行の優先順位
$accepted_args //第四引数(任意）:フックした関数が受け入れられる引数の数
); ?>

任意箇所の解説は省略して、第一引数と第二引数について触れます。

第一引数はフィルターフックの名前とありますが、これはアクションフックでいう
「フックで引っ掛けるタイミング」にあたる部分だと解釈しています。

繰り返しになりますが、フィルターフックは元の内容を加工して出力することが目的なので、
その「元の内容」にあたる部分をここで引っ張ってきているイメージです。

また、第一引数は①独自で作成するオリジナルのもの、②WordPressがあらかじめ設置しているものの２種類があり、
②の場合はWordPress公式指定の名前を、①の場合は自身で設定した関数名などを記載します。
.

第二引数はフックする関数名を任意の名前で記載します。
これも個人的にわかりにくいので、「使用するフィルターの名前」と捉えていますが、
厳密にいうとフィルターが適用されたときに呼び出される関数の名前という表現が正しいようです。

なお、ここでは関数名しか書いていませんが、アクションフックと同じく、
この後で第二引数で指定した関数名に対し、function関数を使って
具体的なフィルターの設定を行うため、ここでは関数名を呼び出してるだけという認識でOKです。
.

次に関数を書く上での注意事項です。

アクションフックとは異なる重要な部分ですが、フィルターフックでは、
フィルターの設定時において、コールバックの記述（return文）が別途必要になります。

詳しくは、後の(2)apply_filters関数を使ってフィルターを実行するで触れますが、
簡単にいうと、フィルターを実行する際に、パラメーターを指定する必要があるためです。

ここでいうパラメーターとは、フィルターで加工した結果を入れておくための入れ物みたいなものです。
つまり、add_filter関数でフィルターの設定を行う段階で、上述のパラメーターに対して、
設定した内容の戻り値（結果）を返すよう記述していく流れとなります。

なお、戻り値がどのような内容なのかについては、WordPress Codexに記述があります。

add_filter関数の戻り値
フィルターフックに関数を登録できると true を、そうでなければ false を返します。

.
.
ここまでの内容をまとめると、以下のような記述方法になります。

<? php
add_filter( フック名, コールバック関数名, 優先順位, 引数の数 );

function コールバック関数($value) {
  //フィルターが適用される際の処理をここに書く
  return $value;  //引数に受け取った値（$value）を加工して返すか変更後の値を返す
}

//（補足）；$valueの部分は任意の名前（ここではひとまずvalueにしているだけです）

.
ちなみここではわかりやいように別途function関数を準備して実行内容を記述していますが、
以下のように、無名関数を使ってadd_filter関数にひとまとめに記述することも可能です。

<? php
add_filter('フック名', function($value){
    //フィルターが適用される際の処理をここに書く
    return $value;  //引数に受け取った値（$value）を加工して返すか変更後の値を返す
});

.
.

(2)apply_filters関数を使ってフィルターを実行する

まずは記述方法から見ていきます。

<?php apply_filters( 
$tag,  //第一引数（必須）：フィルターフックの名前（add_filter関数の第一引数）
$value, //第二引数（必須）：$tag に登録されたフィルター関数が変更できる値
$var//第三引数（任意）：フィルター関数へ渡す追加の変数
); ?>

第一引数はadd_filter関数の第一引数と同じですので、
ここでは第二引数の説明を含め、関数を書く上での注意点のみ以下にまとめておきます。

・(1)add_filter関数でフィルターの設定を行うでも触れた通り、第二引数には、
　フィルターの設定結果（戻り値）を持っているパラメーターを書きます。

・apply_filters関数の機能は「フィルターフックに追加された関数を呼び出す」だけなので、
　フィルターフックを実行する場合はコールバック文も併せて記述する必要があります。

.
ここまでの内容をまとめると、以下のような記述方法になります。

<? php
return apply_filters('フック名', $value);

//（補足）；$valueの部分は任意の名前（ここではひとまずvalueにしているだけです）

.
.

フィルターフックの記述例（練習）

ここまでで書き方のルールはザックリ抑えられたので、実際に練習してみます。
今回は②WordPressがあらかじめ設置しているフィルターフックであるthe_titleを使用します。

事前に書く順番を整理しておきます。

1. add_filter関数を記述してフィルターを設定する
2. apply_filters関数を記述してフィルターを実行する
.

1. add_filter関数を記述してフィルターを設定する

function.php

<? php
add_filter('the_title', function($title){
    return '■'.$title; //文字列連結でタイトルの前に「■」をつけるように設定
});
}

無名関数を使用して投稿タイトルの前に「■」をつけるように設定しています。
なお、パラメーターの名前はWordPressCodexに「$title」と書くよう指定されているため、こちらのルールに則っています。
.

2. apply_filters関数を記述してフィルターを実行する

実は②WordPressがあらかじめ設置しているフィルターフックを使用する場合、
WordPressのコアファイル（wp-includes/post-template.php）に
apply_filters関数が既に記述されています。

中身は以下の通りです。

// wp-includes/post-template.php
function get_the_title( $post = 0 ) {
return apply_filters( 'the_title', $title, $id );
}

内容的には投稿タイトルを取得（get_the_title）する際にフィルターフックを実行し、加工された内容をタイトルとして出力するというイメージですかね。

これでWordPress上の全ての投稿タイトルの頭に「■」が挿入されます。

おわりに

とりあえず概要から把握するために記事を書きましたが、コアファイルの部分など、
潜っていくとかなり深そうなので、ここで止めておきます。

まあ、内容を加工するのに使うんだなあ程度で今はヨシとしよう。。

PHPのフックってなんぞ（フィルターフック編）