WordPress開発者向けチートシート：主要フィルターフック徹底活用ガイド

WordPressの柔軟性を支える重要な仕組みの一つが「フィルターフック」です。アクションフックが特定のタイミングで「処理を追加」するのに対し、フィルターフックはWordPressコアや他のプラグイン・テーマが処理している「データやテキストを変更・加工」するために使われます。適切にフィルターフックを活用することで、サイトの表示内容や内部データを思い通りにカスタマイズできます。

この記事では、WordPress開発で頻繁に使用される主要なフィルターフックをカテゴリ別に分類し、それぞれの役割、使い方、そして具体的なサンプルコードを交えて解説するチートシート形式でまとめました。この知識は、テーマ開発、プラグイン開発、そして既存サイトの高度なカスタマイズに不可欠です。

フィルターフックの基本的な使い方

フィルターフックを利用するには、変更したいデータを受け取り、加工して返す独自の関数（コールバック関数）を定義し、それをadd_filter()関数を使って特定のフィルターフックに登録します。

<?php
// フィルターフックに登録するコールバック関数を定義
// この関数は、フィルター対象のデータ($original_data)を第一引数として受け取ります。
// フックによっては、さらに追加の引数を受け取ることもあります。
function my_custom_filter_function( $original_data, $arg2, $arg3 ) {
    // ここで$original_dataを加工する処理を記述
    $modified_data = strtoupper( $original_data ) . ' - Modified by my filter! (' . $arg2 . ')';
    
    // 必ず加工後のデータを返す (return)
    return $modified_data;
}

// 'the_title' フィルターフックに上記の関数を登録
// 第3引数は優先度 (小さいほど早く実行、デフォルトは10)
// 第4引数はコールバック関数が受け取る引数の数 (デフォルトは1)
// 'the_title'フックは実際には第2引数に$idも渡すので、それを受け取るなら $accepted_args を 2 にする
add_filter( 'the_title', 'my_custom_filter_function', 10, 3 ); // 例として3つの引数を受け取る場合
?>

<?php

// フィルターフックに登録するコールバック関数を定義

// この関数は、フィルター対象のデータ($original_data)を第一引数として受け取ります。

// フックによっては、さらに追加の引数を受け取ることもあります。

function my_custom_filter_function( $original_data, $arg2, $arg3 ) {

// ここで$original_dataを加工する処理を記述

$modified_data = strtoupper( $original_data ) . ' - Modified by my filter! (' . $arg2 . ')';

// 必ず加工後のデータを返す (return)

return $modified_data;

}

// 'the_title' フィルターフックに上記の関数を登録

// 第3引数は優先度 (小さいほど早く実行、デフォルトは10)

// 第4引数はコールバック関数が受け取る引数の数 (デフォルトは1)

// 'the_title'フックは実際には第2引数に$idも渡すので、それを受け取るなら $accepted_args を 2 にする

add_filter( 'the_title', 'my_custom_filter_function', 10, 3 ); // 例として3つの引数を受け取る場合

フィルターフックのコールバック関数では、受け取ったデータを加工した後、必ずその値をreturnで返す必要があります。これを忘れると、データが空になったり、予期せぬエラーが発生したりする原因となります。

主要フィルターフック一覧（カテゴリ別）

WordPressで使用できる主要なフィルターフックを機能別に分類しました。各フックの説明の冒頭には、その利用頻度や重要度を星の5段階評価で示しています。星の数の目安は以下の通りです。
★★★★★：ほぼ全ての開発で頻繁に利用され、基本かつ非常に重要なパラメータ
★★★★☆：高頻度で利用され、多くの一般的なカスタマイズで役立つ重要なパラメータ
★★★☆☆：中程度の頻度で利用され、特定の機能を実現する際に便利なパラメータ
★★☆☆☆：利用頻度はやや低めですが、特定の要件や細かな制御を行いたい場合に役立つパラメータ
★☆☆☆☆：利用頻度は低く、非常に限定的な状況や高度なカスタマイズでのみ使用されるパラメータ

カテゴリ	フック名	役割・説明 (重要度/利用頻度)	主な引数	返すべき値 (型)
コンテンツ表示関連	`the_content`	★★★★★ 投稿や固定ページの本文内容が表示される直前に適用されます。本文の加工、自動挿入などに。	`string $content` (本文)	`string` (加工後の本文)
	`the_title`	★★★★★ 投稿や固定ページのタイトルが表示される直前に適用されます。タイトルに接頭辞を付けたり変更したりできます。	`string $title` (タイトル), `int $id` (投稿ID)	`string` (加工後のタイトル)
	`the_excerpt`	★★★★☆ 投稿の抜粋が表示される直前に適用されます。	`string $excerpt` (抜粋文)	`string` (加工後の抜粋文)
	`excerpt_more`	★★★☆☆ 抜粋の末尾に付加される文字列（デフォルトは`[...]`）を変更します。	`string $more_string` (末尾文字列)	`string` (変更後の末尾文字列)
	`excerpt_length`	★★★☆☆ 自動生成される抜粋の単語数を変更します。	`int $length` (単語数)	`int` (変更後の単語数)
	`wp_get_attachment_image_attributes`	★★★☆☆ `wp_get_attachment_image()`で生成される`<img>`タグの属性を変更します。	`array $attr` (属性の配列), `WP_Post $attachment`, `string\|array $size`	`array` (変更後の属性配列)
	`embed_oembed_html`	★★★☆☆ oEmbed機能で埋め込まれる外部コンテンツのHTMLを変更します。レスポンシブ対応などに。	`string $html` (oEmbedのHTML), `string $url`, `array $attr`, `int $post_id`	`string` (変更後のHTML)
テーマ・テンプレート関連	`body_class`	★★★★★ `<body>`タグに出力されるCSSクラスの配列を変更します。条件に応じたクラス追加に。	`string[] $classes` (クラス配列)	`string[]` (変更後のクラス配列)
	`post_class`	★★★★☆ WordPressループ内で各投稿を囲む要素に出力されるCSSクラスの配列を変更します。	`string[] $classes`, `string\|string[] $class`, `int $post_id`	`string[]` (変更後のクラス配列)
	`template_include`	★★★★☆ WordPressが読み込むテンプレートファイルを動的に変更します。	`string $template` (テンプレートファイルのパス)	`string` (変更後のテンプレートファイルのパス)
	`wp_nav_menu_items`	★★★☆☆ `wp_nav_menu()`で生成されるナビゲーションメニューの項目全体（`<li>`タグ群）を変更します。メニューに検索フォームを追加する際などに。	`string $items` (メニュー項目のHTML), `stdClass $args` (wp_nav_menuの引数)	`string` (変更後のメニュー項目HTML)
	`nav_menu_css_class`	★★★☆☆ ナビゲーションメニューの各`<li>`要素のCSSクラスを変更します。	`string[] $classes`, `WP_Post $item`, `stdClass $args`, `int $depth`	`string[]` (変更後のクラス配列)
	`get_search_form`	★★★☆☆ `get_search_form()`で出力される検索フォームのHTMLを変更します。	`string $form_html` (検索フォームHTML)	`string` (変更後の検索フォームHTML)
	`locale`	★★★☆☆ サイトの現在のロケール（言語設定）を変更します。多言語サイトなどで使用。	`string $locale` (現在のロケール)	`string` (変更後のロケール)
メール関連	`wp_mail_from`	★★★★☆ WordPressから送信されるメールの送信元メールアドレスを変更します。	`string $from_email` (送信元メールアドレス)	`string` (変更後の送信元メールアドレス)
	`wp_mail_from_name`	★★★★☆ WordPressから送信されるメールの送信元名を変更します。	`string $from_name` (送信元名)	`string` (変更後の送信元名)
	`wp_mail_content_type`	★★★☆☆ メールのコンテントタイプ（例: `text/plain`, `text/html`）を変更します。	`string $content_type`	`string` (変更後のコンテントタイプ)
	`wp_mail_charset`	★★★☆☆ メールの文字セットを変更します。	`string $charset`	`string` (変更後の文字セット)
	`wp_mail`	★★★☆☆ `wp_mail()`関数に渡されるパラメータ全体（宛先、件名、本文、ヘッダー、添付ファイル）を変更します。	`array $atts` (パラメータの連想配列)	`array` (変更後のパラメータ配列)
クエリ関連 (WP_Query)	`posts_where`	★★★★☆ `WP_Query`が生成するSQLのWHERE句を直接変更します。高度な絞り込みに。	`string $where` (WHERE句), `WP_Query $query`	`string` (変更後のWHERE句)
	`posts_join`	★★★☆☆ `WP_Query`が生成するSQLのJOIN句を変更します。他のテーブルを結合する場合に。	`string $join` (JOIN句), `WP_Query $query`	`string` (変更後のJOIN句)
	`posts_orderby`	★★★☆☆ `WP_Query`が生成するSQLのORDER BY句を直接変更します。複雑な並び替えに。	`string $orderby` (ORDER BY句), `WP_Query $query`	`string` (変更後のORDER BY句)
	`posts_fields`	★★★☆☆ `WP_Query`が生成するSQLのSELECT句を変更します。取得するフィールドを限定する場合などに。	`string $fields` (SELECT句), `WP_Query $query`	`string` (変更後のSELECT句)
	`posts_limits`	★★★☆☆ `WP_Query`が生成するSQLのLIMIT句を変更します。	`string $limits` (LIMIT句), `WP_Query $query`	`string` (変更後のLIMIT句)
	`found_posts`	★★★☆☆ `WP_Query`で見つかった総投稿数を変更します。ページネーションの計算などに影響します。	`int $found_posts`, `WP_Query $query`	`int` (変更後の総投稿数)
オプション・設定値関連	`pre_option_{option_name}`	★★★★☆ 特定のオプション値 (例: `blogname`) がデータベースから取得される前に、デフォルト値を返したり、動的に値を生成したりできます。	`mixed $value` (デフォルトはfalse), `string $option_name`	`mixed` (返す値。ここで値を返すとDBアクセスは行われない)
	`option_{option_name}`	★★★★☆ データベースから取得された特定のオプション値を変更します。	`mixed $value` (DBから取得した値), `string $option_name`	`mixed` (変更後の値)
	`site_url` / `home_url`	★★★☆☆ それぞれサイトのURL、ホームページのURLを変更します。多言語サイトや特殊な構成の場合に。	`string $url`, `string $path`, `string\|null $scheme`, `int\|null $blog_id`	`string` (変更後のURL)
ユーザー・権限関連	`user_contactmethods`	★★★☆☆ ユーザープロファイル編集画面の連絡先情報に独自の項目を追加します（例: Twitter, Facebookなど）。	`array $methods` (連絡先メソッドの配列)	`array` (変更後の連絡先メソッド配列)
	`login_redirect`	★★★☆☆ ログイン後のリダイレクト先URLを変更します。ユーザーの権限によって振り分けるなど。	`string $redirect_to`, `string $requested_redirect_to`, `WP_User\|WP_Error $user`	`string` (変更後のリダイレクト先URL)
	`registration_errors`	★★★☆☆ ユーザー登録時のバリデーションエラーを変更・追加します。	`WP_Error $errors`, `string $sanitized_user_login`, `string $user_email`	`WP_Error` (変更後のエラーオブジェクト)
管理画面関連	`admin_footer_text`	★★★☆☆ 管理画面のフッター左側に表示されるテキスト（デフォルトは「ご利用ありがとうございます。」）を変更します。	`string $text` (フッターテキスト)	`string` (変更後のフッターテキスト)
	`manage_{$post_type}_posts_columns`	★★★★☆ 投稿タイプごとの一覧画面に表示されるカラム（列）を追加・削除・変更します。	`array $columns` (カラムの配列)	`array` (変更後のカラム配列)
	`upload_mimes`	★★★☆☆ WordPressにアップロードを許可するファイルのMIMEタイプを追加・変更します。SVGの許可など。	`array $mimes` (MIMEタイプの配列)	`array` (変更後のMIMEタイプ配列)

サンプルコード集 (フィルターフック活用例)

1. `the_content`: 記事本文の末尾に署名を追加

<?php
function add_signature_to_content( $content ) {
    if ( is_single() && in_the_loop() && is_main_query() ) { // 個別投稿ページでメインループ内のみ
        $signature = '&lt;p style="text-align:right;font-style:italic;"&gt;この記事は[あなたのサイト名]によって書かれました。&lt;/p&gt;';
        $content .= $signature;
    }
    return $content;
}
add_filter( 'the_content', 'add_signature_to_content' );
?>

<?php

function add_signature_to_content( $content ) {

if ( is_single() && in_the_loop() && is_main_query() ) { // 個別投稿ページでメインループ内のみ

$signature = '<p style="text-align:right;font-style:italic;">この記事は[あなたのサイト名]によって書かれました。</p>';

$content .= $signature;

}

return $content;

}

add_filter( 'the_content', 'add_signature_to_content' );

2. `the_title`: 特定のカテゴリーの投稿タイトルに接頭辞を追加

<?php
function add_prefix_to_special_category_title( $title, $id = null ) {
    if ( in_category('special-news', $id) && !is_admin() ) { // 'special-news' カテゴリーの投稿で、管理画面以外
        $title = "[特集] " . $title;
    }
    return $title;
}
add_filter( 'the_title', 'add_prefix_to_special_category_title', 10, 2 );
?>

<?php

function add_prefix_to_special_category_title( $title, $id = null ) {

if ( in_category('special-news', $id) && !is_admin() ) { // 'special-news' カテゴリーの投稿で、管理画面以外

$title = "[特集] " . $title;

}

return $title;

}

add_filter( 'the_title', 'add_prefix_to_special_category_title', 10, 2 );

3. `body_class`: 特定の固定ページにカスタムCSSクラスを追加

<?php
function my_custom_body_class( $classes ) {
    if ( is_page('contact-us') ) { // スラッグが 'contact-us' の固定ページ
        $classes[] = 'contact-page-style';
        $classes[] = 'theme-light';
    }
    return $classes;
}
add_filter( 'body_class', 'my_custom_body_class' );
?>

<?php

function my_custom_body_class( $classes ) {

if ( is_page('contact-us') ) { // スラッグが 'contact-us' の固定ページ

$classes[] = 'contact-page-style';

$classes[] = 'theme-light';

}

return $classes;

}

add_filter( 'body_class', 'my_custom_body_class' );

4. `wp_mail_from_name`: WordPressからの通知メールの送信者名を変更

<?php
function my_custom_wp_mail_from_name( $original_email_from ) {
    return '私のウェブサイト名';
}
add_filter( 'wp_mail_from_name', 'my_custom_wp_mail_from_name' );
?>

<?php

function my_custom_wp_mail_from_name( $original_email_from ) {

return '私のウェブサイト名';

}

add_filter( 'wp_mail_from_name', 'my_custom_wp_mail_from_name' );

5. `login_redirect`: 購読者ロールのユーザーがログインしたら特定のページにリダイレクト

<?php
function my_custom_login_redirect( $redirect_to, $request, $user ) {
    // ユーザーオブジェクトが存在し、エラーでないことを確認
    if ( isset( $user->roles ) && is_array( $user->roles ) ) {
        // ユーザーが購読者ロール (subscriber) かどうかをチェック
        if ( in_array( 'subscriber', $user->roles ) ) {
            // 購読者専用ページへリダイレクト
            return home_url('/member-dashboard/');
        }
    }
    return $redirect_to; // 他のロールやエラー時はデフォルトのリダイレクト先へ
}
add_filter( 'login_redirect', 'my_custom_login_redirect', 10, 3 );
?>

<?php

function my_custom_login_redirect( $redirect_to, $request, $user ) {

// ユーザーオブジェクトが存在し、エラーでないことを確認

if ( isset( $user->roles ) && is_array( $user->roles ) ) {

// ユーザーが購読者ロール (subscriber) かどうかをチェック

if ( in_array( 'subscriber', $user->roles ) ) {

// 購読者専用ページへリダイレクト

return home_url('/member-dashboard/');

}

return $redirect_to; // 他のロールやエラー時はデフォルトのリダイレクト先へ

}

add_filter( 'login_redirect', 'my_custom_login_redirect', 10, 3 );

よくある質問 (FAQ)

Q1: アクションフックとフィルターフック、結局どう違うのですか？

A1: アクションフックは「処理の実行タイミング」に割り込んで独自の「動作」を追加します。例えば、ヘッダーが読み込まれるタイミングで特定のスクリプトを実行するなど。通常、値を返しません。フィルターフックは「データ」が処理される過程に割り込んでその「値を変更」します。例えば、投稿タイトルが表示される直前にそのタイトル文字列を変更するなど。必ず変更した（あるいは変更しない場合でも元の）値を返します。

Q2: フィルターフックのコールバック関数で、引数で受け取った値を加工した後、returnし忘れるとどうなりますか？

A2:

非常に重要ですが、コールバック関数が値を返さない（またはnullを返す）と、フィルターを通った後のデータが空になったり、期待しない値になったりします。

これにより、サイトの表示が崩れたり、機能が停止したりする可能性があります。フィルターフックでは、必ず最後に加工後のデータ（あるいは変更が不要なら元のデータ）をreturnするようにしてください。

Q3: 同じフィルターフックに複数の関数を登録した場合、どのように実行されますか？

A3: add_filter()の第3引数で指定する「優先度（priority）」の数値が小さい順に実行されます。同じ優先度の場合は、登録された順（通常はfunctions.phpやプラグインの読み込み順）に実行されます。前のフィルターで変更された値が、次のフィルターの引数として渡されていきます。

まとめ

フィルターフックは、WordPressの柔軟性と拡張性を支える屋台骨とも言える機能です。この記事で紹介したフックは、数多く存在するフィルターフックのほんの一部に過ぎませんが、これらを理解し活用することで、WordPressサイトの表示や動作を細部にわたってコントロールできるようになります。ぜひ、実際の開発で試し、その強力なカスタマイズ能力を体験してみてください。

私たちは、歴史ある街並みが魅力の埼玉県川越市を拠点に、お客様のWordPressサイトが持つ可能性を最大限に引き出すためのカスタマイズ、プラグイン開発、そして運用保守サポートを提供しています。地域に根差しながらも、全国のお客様の多様なニーズにお応えしています。

WordPressカスタマイズ・プラグイン開発を気軽にと言わせくださいね。

エーデルハーツ

Custom WordPress Support & Development