1. WordPress

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

Share

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_contentwp_footer, init

まとめ

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

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

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

参考リンク一覧(WordPress公式)