add_filter() の使い方｜説明・引数・注意点

説明

基本構文

add_filter( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 ): true

引数

• $hook_name：フィルターフック名（例：the_content）
• $callback：値を受け取って返すコールバック
• $priority：実行順（既定10）
• $accepted_args：受け取る引数の数（既定1）

戻り値

常に true。

使い方（サンプル）

function my_title_suffix( $title ) {
	return $title . '｜サンプルサイト';
}
add_filter( 'the_title', 'my_title_suffix' );

注意点

• コールバックは必ず値を return します。返し忘れると値が空になります。
• 受け取った型と同じ型を返すのが原則です。
• 管理画面やフィードなど、意図しない場所にも効くことがあるため、必要なら is_admin() などで条件を付けます。

実務での使いどころ

• 値を受け取って、加工して返す処理を、登録するとき（本文、タイトル、メタ情報の調整など）。

よくあるミスと対処

• コールバックで、値を return していない。値が null になり、表示が消える。
• 第4引数（受け取る引数の数）を、指定していない。既定は1つ。
• アクションと、取り違える。アクションは、処理を差し込むもの。
• 優先度を考えていない。他の処理の前後で、結果が変わる。

NG例

add_filter( 'the_title', function ( $title ) {
	$title . '【新着】'; // return がなく、タイトルが空になる
} );

OK例

add_filter( 'the_title', function ( $title, $id ) {
	return in_the_loop() ? $title . '【新着】' : $title;
}, 10, 2 );

使い分け早見表

関連項目

apply_filters()、remove_filter()、add_action()

公式リファレンス：add_filter() | Function | WordPress Developer Resources