WordPressのフィルターフックとは？仕組みとadd_filter()の使い方を解説

WordPressのカスタマイズでよく出てくるのが「add_filter」です。これは既に定義された内容に「変更を加える」ことができるWordPressの関数になります。

当記事では、フィルターフックの仕組みとadd_filter()の使い方について解説していきます。

WordPressのフィルターフックとは？

フィルターフックは「特定のタイミングで内容を変更できる仕組み」のことを指します。こちらを利用することで、既にWordPress側で決められた内容をテーマのfunctions.phpから上書きできるんですね。

例えば、クラシックエディターで文章を入力すると、自動でpタグやbrタグが挿入されますよね。これは、本文を出力する前に実行されるフック「the_content」で、内容に変更を加えているからなんですね。

これらのフィルターフックは、WordPressの中で定義されており、それぞれ固有の名称が付けられています。以下は、一部のフックの名称と実行されるタイミングになります。

the_content	エディターの本文を出力する前
the_title	記事タイトルを出力する前
body_class	bodyにクラス名を出力する前

これらはほんの一部で、WordPressには様々なフックが用意されています。その他のフックが気になる方は以下をご覧ください。

Plugin API/Filter Reference | WordPress Codex

フィルターフック「add_filter()」の基本的な使い方

フィルターフックを利用する際は、WordPress関数の「add_filter()」を使います。

add_filter( $hook_name, $callback, $priority, $accepted_args );

add_filter() – Function | Developer.WordPress.org

「add_filter()」は、指定したフックで任意のコールバック関数を実行できる関数になります。

基本的には、第一引数に「フックの名前」、第二引数に「実行したい関数名」を指定してfunctions.phpに記入します。

// 基本的な使い方
add_filter( 'フックの名前', '実行したい関数名' );

// 例）フック「the_content」で関数「my_function()」を実行したい場合
add_filter( 'the_content', 'my_function' );

それでは、実際に具体的な使い方をみていきましょう。

基本的な使い方
コールバック関数の実行順序を変更
コールバック関数の引数について
フックに登録済みの関数を削除する

基本的な使い方

それでは、add_filter()を使って、管理画面に簡単なカスタマイズをしていきます。今回は「投稿」に関するラベルを変更できるフィルター「post_type_labels_post」を利用していきます。

以下は、管理画面の左メニューにある「投稿」を「ブログ」に変更するカスタマイズですので、テーマのfunctions.phpに記入して正常に動作するかご確認ください。

// 投稿のメニュー名を「ブログ」に変更する
add_filter( 'post_type_labels_post', 'my_post_type_labels_post_filter' );
function my_post_type_labels_post_filter( $labels ){
  $labels->menu_name = 'ブログ';
  return $labels;
}

この「post_type_labels_post」フックでは、コールバック関数の引数に、投稿に関する様々なラベルが格納されています。このラベルを上書きすることで、メニュー名を書き換えているんですね。

add_filter()の基本的な使い方は、「コールバック関数の引数に変更を加えてから返す」のが基本になります。最後に「return」しなければ反映されないので、ご注意ください。

なお、「add_filter()」の第二引数には、無名関数も利用できます。

// 投稿のメニュー名を「ブログ」に変更する
add_filter( 'post_type_labels_post', function( $labels ){
  $labels->menu_name = 'ブログ';
  return $labels;
} );

コールバック関数の実行順序を変更

「add_filter()」の第三引数には、コールバック関数を実行する優先度を数値で指定できます。この数値が小さいものから優先的に実行される仕組みです。

例えば「the_content」に3つの関数をフックした場合、読み込まれた順番に実行されますが、

// 同じフックで複数の関数を実行する
add_filter( 'the_content', 'my_function_a' );
add_filter( 'the_content', 'my_function_b' );
add_filter( 'the_content', 'my_function_c' );

// 実行される順番
1：my_function_a()
2：my_function_b()
3：my_function_c()

第三引数に優先度（数値）を指定すると、指定した数値の小さい順に実行されるようになります。

// 同じフックで複数の関数を実行する
add_filter( 'the_content', 'my_function_a', 20 );
add_filter( 'the_content', 'my_function_b', 30 );
add_filter( 'the_content', 'my_function_c', 10 );

// 実行される順番
1：my_function_c()
2：my_function_a()
3：my_function_b()

これにより、実行順序をよりコントールしやすくなるので非常に便利です。なお、第三引数を省略した場合は優先度が「10」になります。

なお、フィルターフックは内容に変更を加える特性上、後から実行された内容に上書きされてしまいます。反映されない時は、優先度の値を大きくして（999など）実行してみてください。

コールバック関数の引数について

「add_filter()」で実行されるコールバック関数の引数は、利用するフックによって異なります。この引数はフィルターフックを使う上で非常に重要なので、WordPress Developer Resourcesのフック一覧から検索して調べるようにしましょう。

なお、引数を2つ以上利用する場合、第四引数を指定しなければいけない点にご注意ください。

第四引数には、受け入れる引数の数を記入するのですが、この数が合っていないとエラーが発生します。第四引数の初期値は「1」のため、2つ以上の引数を利用する場合は、引数の数を必ず記入するようにしましょう。

例えば、記事タイトルを出力する前に実行されるフック「the_title」では、最大2つまで引数を利用できます。2つとも利用する場合は、第四引数に「2」と記入します。

// 引数を2つ利用する場合は第四引数が必要
apply_filters( 'the_title', function( $post_title, $post_id ){
  // ここで変更処理
  return $post_title;
}, 10, 2 );

フックに登録済みの関数を削除する

ここまで紹介したのは、フックに関数を登録して実行する方法です。この登録した関数は「remove_filter()」を利用することで削除できます。

remove_filter( $hook_name, $callback, $priority );

remove_filter() – Function | Developer.WordPress.org

使い方はシンプルで、第一引数に「フックの名前」第二引数に「登録した関数名」を指定するだけです。

remove_filter( 'フックの名前', '登録済みの関数名' );

// 例）フック「the_content」に登録済みの関数「my_function()」を削除したい場合
remove_filter( 'the_content', 'my_function' );

こちらを利用すれば、WordPressで既に登録されている関数を削除して再登録することも可能です。

apply_filters()でフィルターフックのポイントを作る

一般的には、WordPressで定義されたフィルターフックを使うことが多いですよね。ただし、汎用的に使うテーマやプラグインを開発している場合など、自分のシステムに専用のフックを用意したい時があります。

そんな時は「apply_filters()」で、フィルターフックを自分で作ってみましょう。（フック名は自分で好きな名称を設定できます。）

apply_filters( $hook_name, $value, ...$args );

apply_filters() – Function | Developer.WordPress.org

第一引数に「フック名」、第二引数に「フィルターの対象とする値」、第三引数以降に「コールバック関数に渡したい引数」を指定して利用します。

// my_hookという名称のフックポイントを作成
echo apply_filters( 'my_hook', $value, $args1, $args2, $args3 );

// my_hookを利用する場合
add_filter( 'my_hook', function( $value, $args1, $args2, $args3 ){
  // 内容を変更する処理をここ
  return $value;
} );

ここでコールバック関数内で最後に「return」するのが、第二引数になります。第三引数以降は特に必須ではございません。

apply_filters()を書く場所については、どのPHPファイルでも構いません。自分が実行したいタイミングがあれば、その場所に記入してみてください。