apply_filters_ref_array()创建一个过滤器钩子,并向所有注册到它的过滤器传递一个数组

目录

描述

Execute functions hooked on a specific filter hook, specifying arguments in an array.

This function is identical to apply_filters, but the arguments passed to
the functions hooked to $tag are supplied using an array.

apply_filters_ref_array() 描述

用法

 <?php apply_filters_ref_array$tag$args ); ?> 

apply_filters_ref_array() 用法

参数

$tag

(string) (必填) The name of the action to be executed.

默认值: None

$args

(array) (必填) The arguments supplied to the functions hooked to $tag

默认值: None

apply_filters_ref_array() 参数

注意

  • This function can be useful when your arguments are already in an array, and/or when there are many arguments to pass. Just make sure that your arguments are in the proper order!
  • Before PHP 5.4, your callback is passed a reference pointer to the array. Your callback can use this pointer to access all the array elements. Adding a 过滤器 and declaring a call back that hooks the above example 过滤器 could look like this:
/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
add_filter('my_filter', 'my_callback');
function my_callback( $args ) {
    //access values with $args[0], $args[1] etc.
}

Because the array was passed by reference, any changes to the array elements are applied to the original array outside of the function's scope.

  • Regardless of PHP version, you can specify the number of array elements when adding the 过滤器, and receive each element in a separate parameter in the callback function declaration like so:
/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
add_action('my_filter', 'my_callback', 10, 4 );
function my_callback( $arg1, $arg2, $arg3, $arg4 ) {
    //access values with $args1, $args2 etc.
}

This method copies the array elements into the parameter variables. Any changes to the parameter variables do not affect the original array.

  • As of PHP 5.4, the array is no longer passed by reference despite the function's name. You cannot even use the reference sign '&' because call time pass by reference now throws an error. What you can do is pass the reference pointer as an array element. Doing so does require all callbacks added to the 过滤器 to expect a reference pointer. This is not something you will see in WordPress 动作s. This technique is provided for informational purposes only.
/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
apply_filters_ref_array( 'my_filter', array( &$args ));

add_action('my_filter', 'my_callback');
function my_callback( &$args ) {
    //access values with $args[0], $args[1] etc.
}

Because the original array was passed by reference, any changes to the array elements are applied to the original array outside of the function's scope.

apply_filters_ref_array() 注意

历史

添加于 版本: 3.0.0

apply_filters_ref_array() 历史

源文件

apply_filters_ref_array() 函数的代码位于 wp-includes/plugin.php.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
/**
 * Execute functions hooked on a specific filter hook, specifying arguments in an array.
 *
 * @see 3.0.0
 *
 * @see apply_filters() This function is identical, but the arguments passed to the
 * functions hooked to `$tag` are supplied using an array.
 *
 * @global array $wp_filter         Stores all of the filters
 * @global array $merged_filters    Merges the filter hooks using this function.
 * @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 array  $args The arguments supplied to the functions hooked to $tag.
 * @return mixed The filtered value after all hooked functions are applied to it.
 */
function apply_filters_ref_array($tag, $args) {
	global $wp_filter, $merged_filters, $wp_current_filter;

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

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

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

	// Sort
	if ( !isset( $merged_filters[ $tag ] ) ) {
		ksort($wp_filter[$tag]);
		$merged_filters[ $tag ] = true;
	}

	reset( $wp_filter[ $tag ] );

	do {
		foreach( (array) current($wp_filter[$tag]) as $the_ )
			if ( !is_null($the_['function']) )
				$args[0] = call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));

	} while ( next($wp_filter[$tag]) !== false );

	array_pop( $wp_current_filter );

	return $args[0];
}

apply_filters_ref_array() 源文件

相关