apply_filters_ref_array()

💡 云策文档标注

概述

apply_filters_ref_array() 是 WordPress 中用于调用已添加到过滤器钩子的回调函数的函数，它通过数组传递参数。与 apply_filters() 功能相同，但参数以数组形式提供，适用于参数已为数组或参数较多的情况。

关键要点

函数接受两个参数：$hook_name（过滤器钩子名称，字符串，必需）和 $args（传递给钩子函数的参数，数组，必需）。
返回值是经过所有钩子函数处理后的过滤值。
在 PHP 5.4 之前，数组通过引用传递，回调函数可以直接修改原始数组元素；从 PHP 5.4 起，数组不再通过引用传递，但可通过特定技巧传递引用指针。
可以通过 add_filter() 或 add_action() 指定参数数量，使回调函数以单独参数接收数组元素，此时参数是副本，修改不影响原始数组。
使用时需确保参数顺序正确，并注意 PHP 版本差异对引用传递的影响。

代码示例

$args = array( 'arg_1', true, 'foo', 'arg_4' );
apply_filters_ref_array( 'my_filter', $args );
// 等同于：
apply_filters( 'my_filter', 'arg_1', true, 'foo', 'arg_4' );

注意事项

从 PHP 5.4 开始，尽管函数名包含 "ref"，数组不再通过引用传递，调用时使用引用符号 '&' 会报错。如需传递引用，可将引用指针作为数组元素传递，但这要求所有回调函数都预期接收引用指针，且此技术不常见于 WordPress 操作中，仅供信息参考。

📄 原文内容

Calls the callback functions that have been added to a filter hook, specifying arguments in an array.

Parameters

$hook_namestringrequired: The name of the filter hook.
$argsarrayrequired: The arguments supplied to the functions hooked to $hook_name.

Return

mixed The filtered value after all hooked functions are applied to it.

More Information

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 filter and declaring a call back that hooks the above example filter could look like this:

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 filter, and receive each element in a separate parameter in the callback function declaration like so:

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 filter to expect a reference pointer. This is not something you will see in WordPress actions. This technique is provided for informational purposes only.

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.

Source

function apply_filters_ref_array( $hook_name, $args ) {
	global $wp_filter, $wp_filters, $wp_current_filter;

	if ( ! isset( $wp_filters[ $hook_name ] ) ) {
		$wp_filters[ $hook_name ] = 1;
	} else {
		++$wp_filters[ $hook_name ];
	}

	// Do 'all' actions first.
	if ( isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $hook_name;
		$all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
		_wp_call_all_hook( $all_args );
	}

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

		return $args[0];
	}

	if ( ! isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $hook_name;
	}

	$filtered = $wp_filter[ $hook_name ]->apply_filters( $args[0], $args );

	array_pop( $wp_current_filter );

	return $filtered;
}

View all references View on Trac View on GitHub

Uses	Description
_wp_call_all_hook()`wp-includes/plugin.php`	Calls the ‘all’ hook, which will process the functions hooked into it.

Used by	Description
WP_Term_Query::get_terms()`wp-includes/class-wp-term-query.php`	Retrieves the query results.
WP_Network_Query::get_networks()`wp-includes/class-wp-network-query.php`	Gets a list of networks matching the query vars.
WP_Network_Query::get_network_ids()`wp-includes/class-wp-network-query.php`	Used internally to get a list of network IDs matching the query vars.
WP_Site_Query::get_sites()`wp-includes/class-wp-site-query.php`	Retrieves a list of sites matching the query vars.
WP_Site_Query::get_site_ids()`wp-includes/class-wp-site-query.php`	Used internally to get a list of site IDs matching the query vars.
apply_filters_deprecated()`wp-includes/plugin.php`	Fires functions attached to a deprecated filter hook.
WP_Comment_Query::get_comment_ids()`wp-includes/class-wp-comment-query.php`	Used internally to get a list of comment IDs matching the query vars.
WP_Comment_Query::get_comments()`wp-includes/class-wp-comment-query.php`	Get a list of comments matching the query vars.
WP_Query::set_found_posts()`wp-includes/class-wp-query.php`	Sets up the amount of found posts and the number of pages (if limit clause was used) for the current query.
WP_Query::get_posts()`wp-includes/class-wp-query.php`	Retrieves an array of posts based on query variables.
WP_User_Query::query()`wp-includes/class-wp-user-query.php`	Executes the query, with the current variables.
WP_Meta_Query::get_sql()`wp-includes/class-wp-meta-query.php`	Generates SQL clauses to be appended to a main query.

Show 7 more Show less

Changelog

Version	Description
3.0.0	Introduced.

User Contributed Notes

Skip to note 4 content

Codex

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Example

Call added filters and pass an array of arguments:
```
$args = array( 'arg_1', true, 'foo', 'arg_4' );

apply_filters_ref_array( 'my_filter', $args );
```
This is the same as:
```
apply_filters( 'my_filter', 'arg_1', true, 'foo', 'arg_4' );
```
Log in to add feedback
Skip to note 5 content

Codex

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note

Note

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!

Log in to add feedback
Skip to note 6 content

Codex

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -2You must log in to vote on the helpfulness of this note
As of PHP 5.4, the array is no longer passed by reference

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 filter and declaring a call back that hooks the above example filter could look like this:
```
function wpdocs_my_callback( $args ) {
    // Access values with $args[0], $args[1] etc.
}
add_filter( 'my_filter', 'wpdocs_my_callback' );
```
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 filter, and receive each element in a separate parameter in the callback function declaration like so:
```
function wpdocs_my_callback( $arg1, $arg2, $arg3, $arg4 ) {
    // Access values with $args1, $args2 etc.
}
add_action( 'my_filter', 'wpdocs_my_callback', 10, 4 );
```
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 filter to expect a reference pointer. This is not something you will see in WordPress actions. This technique is provided for informational purposes only.
```
apply_filters_ref_array( 'my_filter', array( &$args ) );

function wpdocs_my_callback( &$args ) {
    //access values with $args[0], $args[1] etc.
}
add_action('my_filter', 'wpdocs_my_callback');
```
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.
Log in to add feedback

云策 WordPress 开发者社区

函数文档