do_action_ref_array()

💡 云策文档标注

概述

do_action_ref_array() 是 WordPress 中用于执行动作钩子的函数，与 do_action() 类似，但通过数组传递参数。它适用于参数已为数组或参数较多的情况，需注意参数顺序和 PHP 版本差异对引用传递的影响。

关键要点

函数功能：调用已添加到动作钩子的回调函数，参数以数组形式提供。
参数说明：$hook_name（字符串，必需）为动作名称；$args（数组，必需）为传递给钩子函数的参数。
PHP 版本差异：PHP 5.4 之前，数组通过引用传递，回调函数可修改原数组；PHP 5.4 及之后，默认不再通过引用传递，需显式传递引用指针。
使用场景：当参数已为数组或参数数量多时，使用此函数可简化代码。
回调函数声明：可通过 add_action() 指定参数数量，在回调中接收独立参数，此时数组元素被复制到参数变量，修改不影响原数组。

代码示例

// 基本用法：传递数组参数
do_action_ref_array( 'my_action', array( 'arg_1', true, 'foo', 'arg_4' ) );

// 与 do_action() 等效
do_action( 'my_action', 'arg_1', true, 'foo', 'arg_4' );

// 引用传递示例（PHP 5.4 前或显式传递）
do_action_ref_array( 'my_action', array( &$args ) );
add_action( 'my_action', 'my_callback' );
function my_callback( &$args ) {
    // 通过 $args[0], $args[1] 访问值
}

// 指定参数数量的回调
do_action_ref_array( 'wpdocs_my_action', array( &$arg1, &$arg2, &$arg3, &$arg4 ) );
add_action( 'wpdocs_my_action', 'wpdocs_my_callback', 10, 4 );
function wpdocs_my_callback( &$arg1, &$arg2, &$arg3, &$arg4 ) {
    // 访问和修改参数值
}

注意事项

确保参数数组的顺序与回调函数期望的参数顺序一致。
在 PHP 5.4 及以上版本中，do_action_ref_array() 默认不通过引用传递数组，需使用 & 符号显式传递引用指针。
如果数组包含对象引用，回调函数可以修改对象的属性。
参考 WordPress 中的 phpmailer_init 动作和 fix_phpmailer_messageid() 回调作为实际应用示例。

📄 原文内容

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

Parameters

$hook_namestringrequired: The name of the action to be executed.
$argsarrayrequired: The arguments supplied to the functions hooked to $hook_name.

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

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

add_action('my_action', '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 action to expect a reference pointer.

do_action_ref_array( 'my_action', array( &$args ) );

add_action('my_action', '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.

If the array contains an object reference, the technique is as follows:

do_action_ref_array( 'my_action', array( &$my_object ) );

add_action('my_action', 'my_callback');
function my_callback( $my_object ) {
// $my_object->some_method()... etc.
}

The object’s properties can be changed. See the action ‘phpmailer_init‘ with the callback fix_phpmailer_messageid() in WordPress for an example.

Source

function do_action_ref_array( $hook_name, $args ) {
	global $wp_filter, $wp_actions, $wp_current_filter;

	if ( ! isset( $wp_actions[ $hook_name ] ) ) {
		$wp_actions[ $hook_name ] = 1;
	} else {
		++$wp_actions[ $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;
	}

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

	$wp_filter[ $hook_name ]->do_action( $args );

	array_pop( $wp_current_filter );
}

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_REST_Widget_Types_Controller::get_widget_form()`wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php`	Returns the output of WP_Widget::form() when called with the provided instance. Used by encode_form_data() to preview a widget’s form.
WP_HTTP_Requests_Hooks::dispatch()`wp-includes/class-wp-http-requests-hooks.php`	Dispatch a Requests hook to a native WordPress action.
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::parse_query()`wp-includes/class-wp-network-query.php`	Parses arguments passed to the network query with default query parameters.
WP_Site_Query::get_sites()`wp-includes/class-wp-site-query.php`	Retrieves a list of sites matching the query vars.
WP_Site_Query::parse_query()`wp-includes/class-wp-site-query.php`	Parses arguments passed to the site query with default query parameters.
do_action_deprecated()`wp-includes/plugin.php`	Fires functions attached to a deprecated action hook.
WP_Comment_Query::get_comments()`wp-includes/class-wp-comment-query.php`	Get a list of comments matching the query vars.
WP_Comment_Query::parse_query()`wp-includes/class-wp-comment-query.php`	Parse arguments passed to the comment query with default query parameters.
WP_Query::setup_postdata()`wp-includes/class-wp-query.php`	Sets up global post data.
WP_User_Search::prepare_query()`wp-admin/includes/deprecated.php`	Prepares the user search query (legacy).
edit_user()`wp-admin/includes/user.php`	Edit user settings based on contents of $_POST
WP_Styles::__construct()`wp-includes/class-wp-styles.php`	Constructor.
wp_mail()`wp-includes/pluggable.php`	Sends an email, similar to PHP’s mail function.
WP::main()`wp-includes/class-wp.php`	Sets up all of the variables required by the WordPress environment.
WP::parse_request()`wp-includes/class-wp.php`	Parses the request to find the correct WordPress query.
WP::send_headers()`wp-includes/class-wp.php`	Sends additional HTTP headers for caching, content type, etc.
WP_Query::the_post()`wp-includes/class-wp-query.php`	Sets up the current post.
WP_Query::have_posts()`wp-includes/class-wp-query.php`	Determines whether there are more posts available in the loop.
WP_Query::set_404()`wp-includes/class-wp-query.php`	Sets the 404 property and saves whether query is feed.
WP_Query::get_posts()`wp-includes/class-wp-query.php`	Retrieves an array of posts based on query variables.
WP_Query::parse_query()`wp-includes/class-wp-query.php`	Parses a query string and sets query type booleans.
WP_Http_Curl::request()`wp-includes/class-wp-http-curl.php`	Send a HTTP request to a URI using cURL extension.
wp_admin_bar_render()`wp-includes/admin-bar.php`	Renders the admin bar to the page based on the $wp_admin_bar->menu member var.
fetch_feed()`wp-includes/feed.php`	Builds SimplePie object based on RSS or Atom feed from URL.
WP_User_Query::prepare_query()`wp-includes/class-wp-user-query.php`	Prepares the query variables.
wp_signon()`wp-includes/user.php`	Authenticates and logs a user in with ‘remember’ capability.
WP_Rewrite::rewrite_rules()`wp-includes/class-wp-rewrite.php`	Constructs rewrite matches and queries from permalink structure.
WP_Scripts::init()`wp-includes/class-wp-scripts.php`	Initialize the class.
WP_Widget::form_callback()`wp-includes/class-wp-widget.php`	Generates the widget control form (Do NOT override).
pingback()`wp-includes/comment.php`	Pings back the links found in a post.

Show 27 more Show less

Changelog

Version	Description
2.1.0	Introduced.

User Contributed Notes

Skip to note 3 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
Basic Example
Call an action and pass an array of arguments:
```
$args = array( 'arg_1', true, 'foo', 'arg_4' );
do_action_ref_array( 'my_action', $args );
```
This is the same as:
```
do_action( 'my_action', 'arg_1', true, 'foo', 'arg_4' );
```
Log in to add feedback
Skip to note 4 content

Chad Cloman

6 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
Here’s a variation on the “separate parameters” example given above. It allows you to specify separate parameters -and- modify them:

Hook:
```
do_action_ref_array( 'wpdocs_my_action', array( &$arg1, &$arg2, &$arg3, &$arg4 ) );
```
Callback:
```
add_action( 'wpdocs_my_action', 'wpdocs_my_callback', 10, 4 );
function wpdocs_my_callback( &$arg1, &$arg2, &$arg3, &$arg4 ) ) {
    // access and modify values with $args1, $args2 etc.
}
```
Log in to add feedback

云策 WordPress 开发者社区

函数文档