WordPressのadd_filterとは？基本的な使い方とフックによるカスタマイズ例を解説

WordPressのカスタマイズにおいて、フィルターフックは非常に強力なツールです。

その中でも、add_filter関数はデータの加工を行うために欠かせない存在となっています。

本記事では、WordPressにおけるadd_filterの基本的な仕組みから、具体的なコードを用いたカスタマイズ例まで詳しく解説します。

初心者の方でも理解しやすいように、実際の開発現場でよく使われるテクニックを盛り込んでいますので、ぜひ参考にしてください。

WordPressのadd_filterとは？

WordPressには「フック（Hook）」と呼ばれる、特定のタイミングで処理を割り込ませる仕組みが備わっています。

フックには大きく分けて「アクションフック」と「フィルターフック」の2種類が存在します。

フィルターフックは、WordPressが保持しているデータを出力する前に加工するために使用されます。

例えば、記事のタイトルに特定の文字を追加したり、本文の文字数を制限したりする場合にフィルターフックを利用します。

一方で、アクションフックは特定のタイミングで「処理を実行する」ために使われるもので、データの返却を前提としていません。

add_filterを使うことで、WordPress本体のコアファイルを書き換えることなく、安全に機能を拡張できるのが大きなメリットです。

add_filterの基本的な構文

add_filter関数を使用する際は、決められた引数を正しく指定する必要があります。

まずは、基本的な書き方を確認してみましょう。

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

それぞれの引数の意味は以下の通りです。

もっとも重要なのは、コールバック関数の中で必ず「return」を使って加工したデータを返さなければならないという点です。

returnを忘れてしまうと、その後の処理でデータが空になってしまい、Webサイトの表示が崩れる原因となります。

優先順位（Priority）の重要性

同じフィルターフックに対して、複数のadd_filterが定義されていることがあります。

例えば、プラグインとテーマの両方で同じデータを加工しようとしている場合です。

この時、$priorityの値を調整することで、どちらの処理を後に適用するかを制御できます。

デフォルト値の10よりも大きな値（例えば20や100）を指定すれば、他の処理が終わった後の最終的なデータに対して変更を加えることが可能です。

add_filterの具体的な使い方とカスタマイズ例

ここからは、実際の開発でよく利用されるadd_filterの具体例をいくつか紹介します。

記事の抜粋文字数を変更する

WordPressのデフォルトでは、記事一覧などで表示される「抜粋（excerpt）」の長さが決まっています。

この長さを変更したい場合は、excerpt_lengthというフィルターフックを使用します。

function my_custom_excerpt_length( $length ) {
    // 抜粋を100文字に変更する
    return 100;
}
add_filter( 'excerpt_length', 'my_custom_excerpt_length', 999 );

このコードでは、デフォルトの数値を上書きして100を返しています。

優先順位を「999」と高く設定することで、テーマ側で設定されているデフォルト値を確実に上書きできるようにしています。

抜粋の末尾の文字列をカスタマイズする

抜粋の最後に表示される「[…]」といった記号を変更したい場合は、excerpt_moreフックを利用します。

function my_custom_excerpt_more( $more ) {
    // 末尾を「... 続きを読む」というリンク付きの文字に変更
    return '... <a href="' . get_permalink() . '">続きを読む</a>';
}
add_filter( 'excerpt_more', 'my_custom_excerpt_more' );

このように記述することで、ユーザーがクリックしやすい形式にカスタマイズできます。

記事本文の最後に定型文を挿入する

すべての投稿の最後に、SNSのフォローボタンや広告、署名などを追加したい場合があります。

その際は、the_contentというフックを使い、本文データに文字列を結合させます。

function add_signature_to_content( $content ) {
    // 投稿ページのみに適用する場合の条件分岐
    if ( is_single() ) {
        $signature = '<div class="signature">ご覧いただきありがとうございました。最新情報はSNSで発信中です。</div>';
        $content .= $signature;
    }
    return $content;
}
add_filter( 'the_content', 'add_signature_to_content' );

この例では、$contentに署名用のHTMLを追加してから返却しています。

条件分岐（is_singleなど）を組み合わせることで、特定のページだけでフィルターを適用させることが可能です。

複数の引数を受け取るフィルターフックの使い方

フィルターフックの中には、加工対象となるデータ以外に、判断材料となる追加の引数を渡してくれるものがあります。

例えば、ナビゲーションメニューのリンク属性を変更するnav_menu_link_attributesなどが該当します。

function my_nav_menu_link_attributes( $atts, $item, $args ) {
    // 特定のメニュー項目にクラスを追加する
    if ( $item->title === 'お問い合わせ' ) {
        $atts['class'] = 'contact-link';
    }
    return $atts;
}
// 引数を3つ受け取るため、第4引数に「3」を指定する
add_filter( 'nav_menu_link_attributes', 'my_nav_menu_link_attributes', 10, 3 );

第4引数の3という指定を忘れると、関数側で定義した$itemや$argsが正しく渡されず、エラーが発生してしまいます。

使用したいフィルターフックがどのような引数を提供しているかは、公式ドキュメント（Code Reference）を確認する習慣をつけましょう。

add_filterを利用する際の注意点

非常に便利なadd_filterですが、実装時に注意すべき点がいくつかあります。

必ず値を返却する

先述した通り、return文は必須です。

もし特定の条件下で加工を行わない場合でも、受け取った元のデータをそのまま返す必要があります。

function my_filter_function( $data ) {
    if ( is_front_page() ) {
        return 'ホームページ用の加工データ';
    }
    // 条件に合致しない場合でも、必ず元のデータを返す
    return $data;
}
add_filter( 'my_hook', 'my_filter_function' );

このreturn $data;を忘れると、フロントページ以外のページで何も表示されなくなる可能性があります。

匿名関数（無名関数）の使用

一度しか使わない簡単な処理であれば、関数名を定義せずに「匿名関数」として記述することもできます。

add_filter( 'the_title', function( $title ) {
    return '【注目】' . $title;
});

ただし、匿名関数で記述するとremove_filterでフックを解除することが困難になります。

プラグイン開発など、後から他の開発者がカスタマイズする可能性がある場合は、名前付きの関数（名前空間を含む）を使用するのがベストプラクティスです。

クラス内でのadd_filterの記述方法

オブジェクト指向プログラミング（OOP）を用いた開発では、クラスのメソッドとしてコールバック関数を定義することが一般的です。

その場合、add_filterの第2引数には配列を渡します。

class My_Theme_Customizer {
    public function __construct() {
        // 自クラス内のメソッドを呼び出す場合は $this を使用
        add_filter( 'excerpt_length', [ $this, 'change_length' ] );
    }

    public function change_length( $length ) {
        return 50;
    }
}
new My_Theme_Customizer();

静的メソッド（static method）を呼び出す場合は、[ 'クラス名', 'メソッド名' ]の形式で指定します。

コードの整理整頓が進んでいる大規模なプロジェクトでは、この形式が多用されます。

フィルターフックの探し方と調査方法

「このデータを変えたいけれど、どのフィルターフックを使えばいいのかわからない」という場面はよくあります。

そのような時は、以下の方法で調査するのが効率的です。

公式開発者ドキュメントを活用する

WordPress公式サイトの「Developer Resources」には、すべてのフックが網羅されています。

フック名の一部を検索窓に入力するだけで、パラメータの意味やサンプルコードを確認できます。

WordPressのソースコードを検索する

WordPress本体のファイル内で、apply_filters( 'フック名', ... )という記述を探すのも有効な手段です。

apply_filtersが記述されている場所こそが、フィルターフックが実行されているタイミングそのものです。

周辺のコードを読むことで、どのようなデータが流れてきているのかを深く理解できます。

Query Monitorプラグインを利用する

開発環境であれば、「Query Monitor」というプラグインを導入することをおすすめします。

現在表示しているページで実行されているすべてのフックを一覧表示できるため、デバッグ作業が劇的にスムーズになります。

よく使われるフィルターフック一覧

頻繁に利用されるフィルターフックをいくつかピックアップして表にまとめました。

これらを組み合わせるだけで、WordPressの挙動を自由自在にコントロールできるようになります。

まずは簡単な文字の追加から試してみて、徐々に複雑なロジックを組み込んでいくと良いでしょう。

まとめ

WordPressのadd_filterは、データを柔軟に加工し、サイトの表示を最適化するための非常に重要な関数です。

「フィルターフックはデータを加工して返すもの」という基本を忘れないようにしましょう。

最後に、今回学んだポイントをおさらいします。

• add_filterはデータの出力前に「加工」を行うための仕組みである。
• コールバック関数内では必ずreturnを使ってデータを返却する。
• 優先順位（Priority）を調整することで、実行される順番を制御できる。
• 複数の引数を受け取る場合は、add_filterの第4引数で個数を明示する。

add_filterを使いこなすことで、WordPressの柔軟性は飛躍的に高まります。

テーマのfunctions.phpや独自プラグインを作成する際に、ぜひ今回の解説を役立ててください。

適切なフックを見つけ出し、最小限のコードで安全にサイトをカスタマイズしていきましょう。