【WordPress】フィルターフックを理解しよう。add_filter()・apply_filters()の使い方を解説

WordPressの柔軟なカスタマイズ性を支える仕組みのひとつに「フィルターフック」があります。

この記事では、add_filter() と apply_filters() の基本的な使い方から、実用的なカスタマイズ事例までをわかりやすく解説します。

フィルターフックの使い方を知りたい方はぜひチェックしてください。

フィルターフックとは？

フィルターフック（Filter Hook）は、WordPressが特定のデータを出力または処理する直前に、そのデータを開発者が変更できる仕組みです。

たとえば、投稿のタイトルやコンテンツ、ウィジェットの出力内容など、様々な場所にフィルターが設けられています。

add_filter() の基本構文

add_filter() は、フィルターフックに独自の関数を追加するための関数です。

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

$hook_name：対象のフィルターフック名（例：the_title）
$callback_function：実行する関数名
$priority（省略可）：実行の優先順位（数字が小さいほど先に実行）
$accepted_args（省略可）：コールバック関数に渡される引数の数

以下は、$priority パラメータに関する補足説明として記事に追加できる内容です。既存記事の「add_filter() の基本構文」または「注意点」セクションの直後に入れるのが自然です。

`$priority` の役割と使いどころ

add_filter() の第3引数で指定できる $priority は、複数のフィルター関数が同じフックに登録されたとき、どの順番で実行するかを制御する値です。初期値は 10 で、数字が小さいほど先に実行されます。

add_filter( 'the_title', 'filter_one', 5 );
add_filter( 'the_title', 'filter_two', 15 );

上記の場合、filter_one() が先に実行され、続いて filter_two() が実行されます。

実行順の調整例

以下のように、優先度を調整して処理順を制御することで、出力結果に影響を与える順序を意図的に設計できます。

function add_prefix( $title ) {
  return '★ ' . $title;
}
add_filter( 'the_title', 'add_prefix', 5 );

function add_suffix( $title ) {
  return $title . ' ★';
}
add_filter( 'the_title', 'add_suffix', 15 );

この例では、タイトルの前後に ★ マークを付加していますが、add_prefix() のほうが先に実行されるため、順序通りに整形されます。

この補足を入れることで、フィルターの実行順に関する誤解を防ぎ、より高度なカスタマイズにも対応できるようになります。必要であれば $accepted_args に関する補足も可能です。

apply_filters() の基本構文

apply_filters() は、データに対して登録されたすべてのフィルターを適用し、その結果を返す関数です。

主にWordPressコアやプラグイン・テーマの内部で使用されます。

$filtered_value = apply_filters( $hook_name, $value, ... );

$hook_name：フック名
$value：変更対象となる値
...：必要に応じて追加の引数を渡せます

実際の使用例

投稿タイトルを変更する

function my_custom_title_filter( $title ) {
  if ( is_singular( 'post' ) ) {
    $title .= '｜オリジナルブログ';
  }
  return $title;
}
add_filter( 'the_title', 'my_custom_title_filter' );

このコードは、投稿のタイトル末尾に「｜オリジナルブログ」を追加します。

`apply_filters()` を使って独自フィルターを作る

自作テーマやプラグインで独自のフィルター処理を行いたいときに使います。

function get_custom_greeting( $name ) {
  $greeting = "こんにちは、{$name}さん！";
  return apply_filters( 'my_custom_greeting', $greeting, $name );
}

この my_custom_greeting フィルターに対して他の開発者が処理を追加できます。

function add_honorific( $greeting, $name ) {
  return $greeting . '（様）';
}
add_filter( 'my_custom_greeting', 'add_honorific', 10, 2 );

よく使われるフィルターフックの例

the_title：投稿や固定ページのタイトル
the_content：投稿本文
excerpt_more：抜粋文の「続きを読む」リンク
widget_text：テキストウィジェットの内容

フィルターフックを使う際の注意点

返り値を必ず返す：フィルター関数では、元の値を加工して返す必要があります。
他のフックと競合しないように関数名はユニークにする：プレフィックスを付けると安全です。
優先度で処理順を調整する：複数のフィルターがある場合、priority を調整して意図通りの動作にしましょう。

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

比較項目	フィルターフック	アクションフック
主な目的	値の加工・変更	特定のタイミングで処理を実行
戻り値	必須（値を返す）	不要（返り値は使われない）
使用例	`the_title`, `the_content`	`wp_footer`, `init`

まとめ

WordPressのフィルターフックを使えば、データの出力内容を柔軟にカスタマイズできます。

add_filter() で処理を追加し、apply_filters() で独自の拡張ポイントを設けることができます。

テーマやプラグインをより柔軟で再利用性の高いものにするために、フィルターフックの理解は欠かせません。