関数リファレンス/add filter

指定したフィルターフックに、関数を登録します。

フィルターは、WordPress が様々な種類のテキストをデータベースまたはブラウザ画面へ送信する前に、それを変更できます。プラグインは、フィルター API を利用して、指定したテキストをその時点で変更する PHP 関数を実行できます。フィルターフックの一覧は プラグイン_API/フィルターフック一覧 を参照してください。

<?php add_filter( $tag, $function_to_add, $priority, $accepted_args ); ?>

$tag

（文字列） （必須） $function_to_add 引数で指定した関数を登録するフィルターフックの名前。フィルターフックの一覧はここにあります。

初期値： なし

$function_to_add

（コールバック） （必須） フィルターが適用されたときに呼び出される関数の名前。

初期値： なし

$priority

（整数） （オプション） フィルターフックに登録された関数の中で、この関数を実行する順序。数値が小さいほど早く実行し、同じ数値の場合は追加された順に実行する。

初期値： 10

$accepted_args

（整数） （オプション） 関数が受け取る引数の個数。WordPress 1.5.1 以降、フィルターフックに登録された関数は、 対応するapply_filters() の実行時に渡される追加の引数を受け取ることができる。

初期値： 1

フィルターフックに関数を登録できると true を、そうでなければ false を返します。ただし、その関数が存在することや、$function_to_add が文字列であることさえもテストしません。面倒を見るのはあなたです。 これは最適化のためであり、できるかぎり高速に実行されます。

WordPress コアの media.php の中で、フィルターフック img_caption_shortcode は次のように呼び出されます：

// プラグインやテーマがデフォルトのキャプション用テンプレートを変更できるようにする。
$output = apply_filters( 'img_caption_shortcode', '', $attr, $content );
if ( $output != '' )
	return $output;

登録されたフィルター関数は 3 つの引数を付けて呼び出されます：

• '' <= フィルターが変更する値を先頭にするのが一般的です。　
• $attr
• $content

フィルター関数が本当にすべての引数を受け取れるように、引数が 3 個あると指定して add_filter() を呼び出さなければなりません。

add_filter( 'img_caption_shortcode', 'my_img_caption_shortcode_filter', 10, 3 );

/**
 * [caption] ショートコード文字列を HTML5 準拠のコードに置き換えるフィルター
 *
 * @return text HTML で記述した、埋め込まれる画像の説明
 **/
function my_img_caption_shortcode_filter( $val, $attr, $content = null )
{
	extract( shortcode_atts( array(
		'id'	  => '',
		'align'	  => '',
		'width'	  => '',
		'caption' => ''
	), $attr ) );
	
	if ( 1 > (int) $width || empty($caption) )
		return $val;

	$capid = '';
	if ( $id ) {
		$id = esc_attr( $id );
		$capid = 'id="figcaption_'. $id . '" ';
		$id = 'id="' . $id . '" aria-labelledby="figcaption_' . $id . '" ';
	}

	return '<figure ' . $id . 'class="wp-caption ' . esc_attr( $align ) . '" style="width: '
	. ( 10 + (int) $width ) . 'px">' . do_shortcode( $content ) . '<figcaption ' . $capid 
	. 'class="wp-caption-text">' . $caption . '</figcaption></figure>';
}

• フックに登録された関数は、対応する do_action() または apply_filters() の実行時に渡される追加の引数を受け取れます。例えば、アクションフック 'comment_id_not_found' /en はコメント ID を各コールバック関数へ渡します。

• $accepted_args で指定した個数の引数を渡せますが、値を変更して返すことができるのは $value だけです。他の引数はコンテキストを与えるだけで、その値をフィルター関数で変更することはできません。

• コールバックとしてクラスのメソッドを登録することもできます。

静的なクラスメソッド:

add_filter( 'media_upload_newtab', array( 'My_Class', 'media_upload_callback' ) );

インスタンスのメソッド:

add_filter( 'media_upload_newtab', array( $this, 'media_upload_callback' ) );

• コールバックとして無名関数を登録することもできます。例えば:

add_filter( 'the_title', function( $title ) { return '<b>' . $title . '</b>'; } );

無名関数 は PHP 5.3.0 で導入されました。これを使う前に、サーバーの用意 /en に記載の要件とあなたの PHP のバージョンを確認してください。

あなたの PHP のバージョンが 5.3.0 より古い場合、代わりに create_function() が利用できます。ただし、create_function() で作る匿名関数は PHP の APC や他のオプティマイザーでキャッシュされません。そのため、コールバックが何度も使われたり複雑なロジックを実行したりする場合は、create_function() を使わないでください。

• 新規導入: 0.71

add_filter() は wp-includes/plugin.php にあります。

• A good explanation on Filter hooks on stackoverflow.com (2012-12-10)

フィルター: has_filter(), add_filter(), apply_filters(), current_filter(), remove_filter(), remove_all_filters()

最新英語版： WordPress Codex » Function_Reference/add_filter （最新版との差分）