apply_filters()の使い方と作り方のサンプルコード

WordPressのプラグインやテーマカスタマイズでよく出てくるフィルターフック。

〇〇プラグインの△△を変える．．みたいなことに対するヒントとして紹介されているものではこれらがさらっと使われた完成コードが紹介されていますね。

用途を満たすならそのコードをコピペで済むものの、そもそもフィルターフックって何？何でそうなるの？と思ったことはないでしょうか？

本ページでは、フィルターフックを使えるようにする「appply_filters」という関数の使い方と、使えるようになったフィルターの使い方（フィルターフックの使い方）をコードサンプルとともに自身の備忘録を兼ね紹介しておきます。

自身のテーマ作成やプラグイン作成時にも利用できる手法ですし、既存のテーマ・プラグインでコードを使ってカスタマイズできる部分を知る上でも有用ですヨ。

ページ内の用語の呼称や表現方法が微妙なところがありますがご容赦ください

apply_filters()って何？

apply_filters()という関数は、直接プログラムを書き換えなくても、どこか（例えばテーマのfunctions.phpなど）から特定の部分を書き換えられるように用意されているもので、テーマやプラグインのいろいろな箇所で使用されています。

以下がapply_filters()が設置されている簡単なプログラムコードサンプルです。

function pwcn_wp_head_add_text() {
 $text = '元のテキスト';
 $text = apply_filters( 'pwcn_wp_head_add_text_filter', $text );

 echo '<p>'.$text.'</p>';
}
add_action('wp_head','pwcn_wp_head_add_text');

このコードでは以下のことをしています。

• pwcn_wp_head_add_text()というユーザー定義関数の内容をadd_action(アクションフック)を使ってwp_head(サイトのヘッダー)へ反映させる
• pwcn_wp_head_add_text()というユーザー定義関数では、$textの値をechoで出力する
• $textの値は「元のテキスト」とする
• apply_filters()を使って、$text(元のテキスト)を書き換え可能にする
  • 書き換える場合には「pwcn_wp_head_add_text_filter」という関数を使い、add_filterを使ってフック（後から上書き）させる
  • 書き換える内容は「$text」の内容

簡単に言えば、そもそもプログラムで指定されているのは$textとして指定されている「元のテキスト」という文字列なのだが、フィルターフックでこの$textを書き換えられるようにしているよ！というものなのです。

こうなっていることで、例えばプラグインからサイトの表示画面上の文字列を変更するということが簡単にできるようになり、わざわざプログラムを書き換える必要もなくなり、プラグインを更新しても元に戻ることがないという仕組みを作ることができます。

また、apply_filters()関数は「指定したフィルターにフックする（割り込む）」プログラムがあれば適用し、なければ無視するようになっているので、使うかどうか分からないけどひとまずこの条件は書き換えられるようにしておこうという形で入れておくこともできますし、プラグインの停止などによって、テーマへ書いたフックするプログラムだけが存在してしまう状況でも無視されますから、サイトがストップしてしまうということも少ないです。

以上がapply_filters()の特徴です。

ここまでで、なんとなく仕組みは感覚的に理解いただけたのではと思いますが、例えばプラグインにそのようにフィルターが用意されていても、いったいどうやって変更の指示をすればいいの？となってしまいますね。

プラグインのマニュアルやWordPress公式、あまたある参考ページを見ても「フックさせればいい」などと素っ気なく書かれているので「はて？」となってしまう方も少なくないと思います。

そこで次項では、テーマのfunctions.phpなどへ記述して具体的な指示を行う方法を、コード例を交えて紹介します。

用意されているフィルターを使う（変更を適用する）方法

フィルター（変更）のかけ方

まずは、プラグインやテーマの説明などで「利用可能なフィルターフック一覧」などとして紹介されているフィルターを使う方法について、前項のサンプルプログラムに書かれているフィルター可能な項目に対して、フィルターを適用させる具体例を紹介します。

前項のサンプルプログラムに書かれているフィルター機能を利用して「元のテキスト」文字列を書き換えるのが以下のコードです。

function pwcn_change_text() {
 $new_text = '追加したテキスト';

 $text = $new_text;
 return $text;
}
add_filter( 'pwcn_wp_head_add_text_filter', 'pwcn_change_text' );

最終行で、「pwcn_change_text」という名前の関数の内容を「pwcn_wp_head_add_text_filter」という場所へ、「add_filter」で上書き（フック）してというのが動作自体の指示内容です。

指示しているのは「pwcn_change_text」の内容で、「追加したテキスト」という文字列を「$text」という変数にして、returnで「$text」を返すということをしています。

つまりは、「$text」の内容を「追加したテキスト」に変えたいよ！変えるのはプログラムの中で「pwcn_wp_head_add_text_filter」が書かれている場所だよ！ということをしています。

前項のサンプルプログラムには以下の記述がありましたね。

$text = apply_filters( 'pwcn_wp_head_add_text_filter', $text );

これは$textという変数に格納された文字列を「pwcn_wp_head_add_text_filter」で書き換え可能にして、$textに再格納するという意味なので、上記のコードで「元の文字列」が「追加したテキスト」へ書き換えられるのです。

今回は単純なコードで説明しましたが、何に（今回は$text）、何のフィルターを使って（今回はpwcn_wp_head_add_text_filter）変更するのかという書き方自体はどんな場合でも変わらないので、これが基本と覚えておけばまずは間違いないでしょう。

今あるテキストの後ろにカスタムテキストを追加する場合のコード例

前項では、単純にテキストを変える（変更する）コードを紹介しましたが、補足として「元のテキスト」の後ろに何かを追加したい場合のコード例を紹介しておきます。

以下のようにユーザー定義関数の()へ元の変数である$textを入れ、コード中の「=」の前に「.」を付けて、「.=」とすると実現できます。

function pwcn_change_text( $text ) {
 $new_text = '追加したテキスト';

 $text .= $new_text;
 return $text;
}
add_filter( 'pwcn_wp_head_add_text_filter', 'pwcn_change_text' );

アクションフック（add_action）とは違い、フィルターフックは存在しなければ無視されるため、フィルターフックのみが存在してもエラーとなることはありませんので安心して使える反面、反映されないこともあるので注意しましょう。

フィルターの探し方

テーマやプラグインのプログラムやWordPress本体のプログラムの中には、フィルター（aply_filters()で書き換え可能にしている）は用意していても、一覧などで明示されていない場合や、調べないと分からない場合などがあります（個人的には調べないと分からないものの方が有用なことが多い気がします）。

利用できるフィルターは以下のプラグインを使うことで簡単に調べることができます。

String locator

有効化すると、「ツール」メニューに「String Locator」という項目が出てくるので、それを開き、目的なテーマやプラグインを指定してから、キーワードへ「apply_filters」と入れて検索すれば、そのテーマやプラグインでフィルターとして使用可能になっているものがずらっと表示されます。

フィルター名には「どの部分に？」というヒント（例えば前述のコードであれば「text」などという文字列）が使われていることが多いので、一覧上にあるフィルター名から想像して、目的と思われるプログラムを開き、何が変更できるものなのかを確認するといいでしょう。

前述した通り、フィルターの適用方法（フックのかけ方）は基本同じなので、テーマのfunctions.phpなどで試しにコードを作って変更されるかは確認できますから、まずは手を動かして探るようにしましょう。

独自プログラム内にフィルターを設ける方法

出力している文字列を他の文字列に変更する場合のコード例

フックのかけ方が分かれば恐らくどうやってフィルターを設ければいいのかは分かると思いますが一応．．。

テーマ内などへ自身で書いた以下のようなコードがあったとします。

function pwcn_wp_head_add_text() {
 $text = '元のテキスト';
 
 echo '<p>'.$text.'</p>';
}
add_action('wp_head','pwcn_wp_head_add_text');

このままだと、コードそのものを変えるか、このコードよりも先に読み込まれるような位置に同じコードを書いて「元のテキスト」という文字列を変更するしかカスタマイズ方法はありません。

そのサイトだけのために書いているコードなら、このままでも構いませんし、その場で書き換えれば使いまわすこともできます。

ただ、汎用にする（誰かに配布したりする）場合には、書き換えられるようにしておいた方が便利ですし、プログラム自体を上書き更新してしまって変更の指示をした部分が台無しになることもなくなるので、以下のように変更して、文字列を後から変更可能にするフィルター（apply_filters）化しておくと便利です。

function pwcn_wp_head_add_text() {
 $text = '元のテキスト';
 $text = apply_filters( 'pwcn_wp_head_add_text_filter', $text );

 echo '<p>'.$text.'</p>';
}
add_action('wp_head','pwcn_wp_head_add_text');

以下が最初のコードとの違い。

• 3行目の$textという変数で、最初の行では「元のテキスト」という文字列を設定
• 4行目で、$textという変数に対し、別の場所から「pwcn_wp_head_add_text_filter」というフィルターフックを使って$textの値を指定することで文字列を変更できるよう「apply_filters」関数を使って再指定する

この処理を追加したことで、いつでも「pwcn_wp_head_add_text_filter」というフィルターフックを使って文字列が変更できる準備ができているので、以下のようなユーザー定義関数とフィルターフックを使って、文字列の変更ができます。

apply_filters()を複数指定することもできる

例えば、「複数のプログラムに対して共通したフィルターを設けておきたいけど、この関数に対してだけに適用させるものも作りたい」という場合に有効な方法です。

冒頭で紹介した以下のコードをこの形に変更して使用します。

【変更前】

function pwcn_wp_head_add_text() {
 $text = '元のテキスト';
 $text = apply_filters( 'pwcn_wp_head_add_text_filter', $text );

 echo '<p>'.$text.'</p>';
}
add_action('wp_head','pwcn_wp_head_add_text');

【変更後】

function pwcn_wp_head_add_text() {
 $text = '元のテキスト';
 $text = apply_filters( 'pwcn_wp_head_add_text_filter', $text );
 $text = apply_filters( 'pwcn_wp_head_add_text_filter_custom', $text );

 echo '<p>'.$text.'</p>';
}
add_action('wp_head','pwcn_wp_head_add_text');

見比べていただくと分かる通り、簡単に言えば、フィルター用関数名の異なるaply_filters()を2つ使います。

4行目に書かれているのは、変更前と同じ「pwcn_wp_head_add_text_filter()」で$textを書き換えるためのフックです。そしてこのフィルター用関数名は他のプログラムでも同じものを使っているものとします。

ここへ新たに5行目書かれている、同じ$textを書き換えるためのフックを入れます。

ただし、フック用の関数名が「pwcn_wp_head_add_text_filter_custom()」と4行目とは異なります。

こうして複数のフィルター用関数を入れておくことで以下のようにさせることができます。

• フィルター用関数名へフィルターフックさせるプログラムがなければ「元のテキスト」を$textとする
• 「pwcn_wp_head_add_text_filter()」へフックさせるプログラムがあればその文字列を$textとする
• 「pwcn_wp_head_add_text_filter_custom()」へフックさせるプログラムがあればその文字列を$textとする

同じ$textに対して3つの方法で指示を出しているものの、「pwcn_wp_head_add_text_filter_custom()」が一番下に書かれていて、PHPでは一番下に書かれているものが最優先になるので、これにフックさせるプログラムがあれば、前の2つよりも優先して適用させることができるようになります。

【補足】関数の後ろにある()の役割

カスタマイズ情報によくある、「このコードをテーマのfunctions.phpへ追加して．．」というコードを見て、不思議に思ったことありませんか？

例えばこのページのここに出てくる以下のコードには()に中身がありませんね。

function pwcn_change_text() {
 $new_text = '追加したテキスト';

 $text = $new_text;
 return $text;
}
add_filter( 'pwcn_wp_head_add_text_filter', 'pwcn_change_text' );

でもそのすぐ下に掲載している以下のコードでは、()に$textと書かれています。

function pwcn_change_text( $text ) {
 $new_text = '追加したテキスト';

 $text .= $new_text;
 return $text;
}
add_filter( 'pwcn_wp_head_add_text_filter', 'pwcn_change_text' );

このケースでは、どちらも$textという値を最終的にreturnで返していて、それを受け取るapply_filters()でも以下のように$textという変数の値を受け取っているので、1対1で他に渡す値がないため、()内はあってもなくても動作します。

$text = apply_filters( 'pwcn_wp_head_add_text_filter', $text );

ただ中には渡す引数（ここで例示している$textのこと）が同じフィルターで別のものを使っていたりするケースがあったりするので、できれば渡す引数が1対1の場合でもきちんと()内に渡す引数を指示しておいた方がいいでしょう。

以上、apply_filters()関数の使用方法（使う側、作る側）でした。

今回はテキストの変更をさせるサンプルコードとして紹介しましたが、投稿タイプを指定する、IDを指定するなどいろいろな用途に使えるので覚えておくと便利です。

apply_filters()

全くの余談ですが．．「フック」「フィルター」「関数」「フィルターフック」「フックさせる」などいろいろな言葉をなるべく分かりやすく書いたつもりですが、言葉に明確な定義がないので、この手の使い方を紹介する文章はいつ書いても難しいです（笑）。

理解しにくい部分があるかもしれませんがご容赦ください。