SYNCER

SYNCER

apply_filters() - フィルターイベントを発火する

公開日:

apply_filters()は、指定したフィルターイベントを発火する関数です。フィルターにフックされた各関数の処理を通して加工されたデータを返り値として受け取ります。フィルター名はオリジナルのものを含めて自由に指定できます。

構文

mixed apply_filters( string $tag, mixed $value, mixed $... )

パラメータ

$tag

イベントの名前。

$value

フィルター対象の値。この値が各関数で加工処理を経て返り値となる。

$...

第3引数以降に指定した引数は、各関数に引数として渡される。

返り値

mixed

各関数の加工処理された第2引数の値。

関数

この関数内で利用している、別のWordPress関数です。

  • _wp_call_all_hook()

サンプルコード

フィルターイベントを発火する

ここでは_hogeという適当な名前のフィルターイベントを発火させてみます。フックしたのは、値の末尾に"DEF"という文字列を追加して返す関数です。

php

<?php
// 関数の内容
function _fire ( $data ) {
	// データを加工して返す
	return $data . "DEF" ;
}

// フィルターに関数を紐付ける
add_filter( '_hoge', '_fire' );

// 実行 ("ABC"という値をフィルターにかける)
$result = apply_filters( '_hoge', "ABC" ) ;

// 結果
var_dump( $result ) ;

結果 (出力内容) - PHP7.0.13

string(6) "ABCDEF"

引数を渡す

第3引数以降は可変で指定でき、それらは各関数に引数として渡されます。加工処理の際に補助となる情報が必要な場合に有用です。なお、フィルターにフックをかける時(add_filter()の実行時)に、受け取る引数の数を指定しなければいけません。

php

<?php
// 関数の内容
function _fire ( $data, $arg1, $arg2 ) {
	// 引数の中身を表示
	echo '$data: ' . $data . "\n" ;
	echo '$arg1: ' . $arg1 . "\n" ;
	echo '$arg2: ' . $arg2 . "\n" ;
}

// フィルターに関数を紐付ける
add_filter( '_hoge', '_fire', 10, 3 );

// 実行
apply_filters( '_hoge', "ABC", "AAAA", "BBBB" ) ;

結果 (出力内容) - PHP7.0.13

$data: ABC
$arg1: AAAA
$arg2: BBBB

ソースコード

wp-includes/plugin.php

/**
 * Call the functions added to a filter hook.
 *
 * The callback functions attached to filter hook $tag are invoked by calling
 * this function. This function can be used to create a new filter hook by
 * simply calling this function with the name of the new hook specified using
 * the $tag parameter.
 *
 * The function allows for additional arguments to be added and passed to hooks.
 *
 *     // Our filter callback function
 *     function example_callback( $string, $arg1, $arg2 ) {
 *         // (maybe) modify $string
 *         return $string;
 *     }
 *     add_filter( 'example_filter', 'example_callback', 10, 3 );
 *
 *     /*
 *      * Apply the filters by calling the 'example_callback' function we
 *      * "hooked" to 'example_filter' using the add_filter() function above.
 *      * - 'example_filter' is the filter hook $tag
 *      * - 'filter me' is the value being filtered
 *      * - $arg1 and $arg2 are the additional arguments passed to the callback.
 *     $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );
 *
 * @since 0.71
 *
 * @global array $wp_filter         Stores all of the filters.
 * @global array $wp_current_filter Stores the list of current filters with the current one last.
 *
 * @param string $tag     The name of the filter hook.
 * @param mixed  $value   The value on which the filters hooked to `$tag` are applied on.
 * @param mixed  $var,... Additional variables passed to the functions hooked to `$tag`.
 * @return mixed The filtered value after all hooked functions are applied to it.
 */
function apply_filters( $tag, $value ) {
	global $wp_filter, $wp_current_filter;

	$args = array();

	// Do 'all' actions first.
	if ( isset($wp_filter['all']) ) {
		$wp_current_filter[] = $tag;
		$args = func_get_args();
		_wp_call_all_hook($args);
	}

	if ( !isset($wp_filter[$tag]) ) {
		if ( isset($wp_filter['all']) )
			array_pop($wp_current_filter);
		return $value;
	}

	if ( !isset($wp_filter['all']) )
		$wp_current_filter[] = $tag;

	if ( empty($args) )
		$args = func_get_args();

	// don't pass the tag name to WP_Hook
	array_shift( $args );

	$filtered = $wp_filter[ $tag ]->apply_filters( $value, $args );

	array_pop( $wp_current_filter );

	return $filtered;
}

参考リンク