add_filter() - フィルターイベントと関数を紐付ける

bool add_filter( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 )

php

<?php
// 関数の内容
function _fire ( $data ) {
	echo "発火しました。" ;
}

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

// '_hoge'というフィルターイベントを発火
apply_filters( '_hoge', "ABC" ) ;

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

発火しました。

php

<?php
// 関数の内容
function aaa ( $data ) {
	return $data . "BBB" ;
}

function bbb ( $data ) {
	return $data . "CCC" ;
}

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

// '_hoge'というフィルターイベントを発火
$result = apply_filters( '_hoge', "AAA" ) ;

// 結果
var_dump( $result ) ;

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

string(9) "AAABBBCCC"

php

<?php
// 関数の内容
function _fire ( $data, $arg1=null, $arg2=null ) {
	echo '$arg1: ' . $arg1 . "\n" ;
	echo '$arg2: ' . $arg2 . "\n" ;
}

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

// '_hoge'というフィルターイベントを発火
apply_filters( '_hoge', "AAA", "補助情報1", "補助情報2" ) ;

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

$arg1: 
$arg2:

php

<?php
// 関数の内容
function _fire ( $data, $arg1=null, $arg2=null ) {
	echo '$arg1: ' . $arg1 . "\n" ;
	echo '$arg2: ' . $arg2 . "\n" ;
}

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

// '_hoge'というフィルターイベントを発火
apply_filters( '_hoge', "AAA", "補助情報1", "補助情報2" ) ;

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

$arg1: 補助情報1
$arg2: 補助情報2

php

<?php
// フィルターに無名関数を紐付ける
add_filter( '_hoge', function ( $data ) {
	// データを加工する
	return $data . "DEF" ;
} );

// 実行
$result = apply_filters( '_hoge', "ABC" ) ;

// 結果
var_dump( $result ) ;

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

string(6) "ABCDEF"

wp-includes/plugin.php

/**
 * Hook a function or method to a specific filter action.
 *
 * WordPress offers filter hooks to allow plugins to modify
 * various types of internal data at runtime.
 *
 * A plugin can modify data by binding a callback to a filter hook. When the filter
 * is later applied, each bound callback is run in order of priority, and given
 * the opportunity to modify a value by returning a new value.
 *
 * The following example shows how a callback function is bound to a filter hook.
 *
 * Note that `$example` is passed to the callback, (maybe) modified, then returned:
 *
 *     function example_callback( $example ) {
 *         // Maybe modify $example in some way.
 *         return $example;
 *     }
 *     add_filter( 'example_filter', 'example_callback' );
 *
 * Bound callbacks can accept from none to the total number of arguments passed as parameters
 * in the corresponding apply_filters() call.
 *
 * In other words, if an apply_filters() call passes four total arguments, callbacks bound to
 * it can accept none (the same as 1) of the arguments or up to four. The important part is that
 * the `$accepted_args` value must reflect the number of arguments the bound callback *actually*
 * opted to accept. If no arguments were accepted by the callback that is considered to be the
 * same as accepting 1 argument. For example:
 *
 *     // Filter call.
 *     $value = apply_filters( 'hook', $value, $arg2, $arg3 );
 *
 *     // Accepting zero/one arguments.
 *     function example_callback() {
 *         ...
 *         return 'some value';
 *     }
 *     add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1.
 *
 *     // Accepting two arguments (three possible).
 *     function example_callback( $value, $arg2 ) {
 *         ...
 *         return $maybe_modified_value;
 *     }
 *     add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2.
 *
 * *Note:* The function will return true whether or not the callback is valid.
 * It is up to you to take care. This is done for optimization purposes, so
 * everything is as quick as possible.
 *
 * @since 0.71
 *
 * @global array $wp_filter      A multidimensional array of all hooks and the callbacks hooked to them.
 *
 * @param string   $tag             The name of the filter to hook the $function_to_add callback to.
 * @param callable $function_to_add The callback to be run when the filter is applied.
 * @param int      $priority        Optional. Used to specify the order in which the functions
 *                                  associated with a particular action are executed. Default 10.
 *                                  Lower numbers correspond with earlier execution,
 *                                  and functions with the same priority are executed
 *                                  in the order in which they were added to the action.
 * @param int      $accepted_args   Optional. The number of arguments the function accepts. Default 1.
 * @return true
 */
function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
	global $wp_filter;
	if ( ! isset( $wp_filter[ $tag ] ) ) {
		$wp_filter[ $tag ] = new WP_Hook();
	}
	$wp_filter[ $tag ]->add_filter( $tag, $function_to_add, $priority, $accepted_args );
	return true;
}