剖析 WordPress `do_action_ref_array()` 函数的源码：如何通过引用传递参数给 `action` 钩子。

各位听众，早上好/下午好/晚上好！ 今天咱们来聊聊WordPress里一个看似不起眼，实则暗藏玄机的函数：do_action_ref_array()。 这家伙就像个默默无闻的媒婆，专门负责给各个 action 钩子牵线搭桥，让参数们以一种特别的方式见面——引用传递！ 准备好了吗？咱们这就开始解剖它的源码，看看它到底是怎么玩的。

1. Action 钩子的基本概念：WordPress 的事件发布系统

在深入 do_action_ref_array() 之前，先要搞清楚 action 钩子是个什么玩意。简单来说，它就是 WordPress 的一个事件发布系统。 当某个特定的事件发生时（比如文章发布、主题加载），WordPress 会发出一个“信号”，也就是触发一个 action 钩子。

其他开发者可以通过 add_action() 函数，把自己的代码（函数）“挂”到这个钩子上。 这样，当这个钩子被触发时，所有挂在它上面的函数都会被依次执行。 这就实现了代码的解耦，让不同的模块可以独立地对同一个事件做出反应。

2. do_action()：最常见的 Action 触发器

do_action() 是我们最常用的触发 action 钩子的函数。它的基本用法如下：

do_action( 'my_custom_action', $arg1, $arg2, ... );

这里的 'my_custom_action' 就是钩子的名称， $arg1, $arg2 等等是要传递给挂在这个钩子上的函数的参数。 注意，默认情况下，do_action() 是按值传递参数的。这意味着，在钩子函数内部修改参数的值，不会影响到原始变量。

3. do_action_ref_array()：引用传递的秘密武器

do_action_ref_array() 和 do_action() 非常相似，唯一的区别在于，它通过引用传递参数。 这意味着，如果钩子函数内部修改了参数的值，原始变量也会受到影响！

do_action_ref_array() 的基本用法是：

do_action_ref_array( 'my_custom_action', array( &$arg1, &$arg2, ... ) );

注意，这里的参数必须放在一个数组里，并且每个参数前面都要加上 & 符号，表示引用传递。

4. 源码剖析：do_action_ref_array() 的内部实现

让我们深入到 WordPress 的源码中，看看 do_action_ref_array() 到底是怎么实现的。 它的定义通常在 wp-includes/plugin.php 文件中。

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

    if ( ! isset( $wp_filter[ $hook ] ) ) {
        return;
    }

    if ( isset( $wp_actions[ $hook ] ) ) {
        ++$wp_actions[ $hook ];
    } else {
        $wp_actions[ $hook ] = 1;
    }

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

    if ( isset( $wp_filter[ $hook ] ) ) {
        $wp_current_filter[] = $hook;
        _wp_call_hook( $hook, $args );
    }

    array_pop( $wp_current_filter );
}

让我们逐行分析：

• global $wp_filter, $wp_actions, $wp_current_filter;： 这行代码声明了三个全局变量，它们分别是：

  • $wp_filter： 存储所有已注册的钩子及其对应的函数。 它是一个多维数组，键是钩子的名称，值是一个数组，包含了所有挂在这个钩子上的函数。
  • $wp_actions： 记录每个 action 钩子被触发的次数。
  • $wp_current_filter： 一个堆栈，用于跟踪当前正在执行的 action 钩子。

• if ( ! isset( $wp_filter[ $hook ] ) ) { return; }： 如果指定的钩子 $hook 还没有被注册（也就是没有函数挂在它上面），就直接返回，不做任何事情。

• if ( isset( $wp_actions[ $hook ] ) ) { ++$wp_actions[ $hook ]; } else { $wp_actions[ $hook ] = 1; }： 更新 $wp_actions 数组，记录当前钩子被触发的次数。

• if ( isset( $wp_filter['all'] ) ) { ... }： WordPress 还有一个特殊的钩子叫做 all。 如果有函数挂在这个钩子上，那么每次触发任何其他的 action 钩子时，all 钩子上的函数都会被执行。

• if ( isset( $wp_filter[ $hook ] ) ) { ... }： 这是最关键的部分。 如果指定的钩子 $hook 已经注册了，就调用 _wp_call_hook() 函数，执行所有挂在这个钩子上的函数。 注意，这里传递了 $args 数组，也就是我们传递的参数。

现在，让我们看看 _wp_call_hook() 函数的实现：

function _wp_call_hook( $hook, $args ) {
    global $wp_filter;

    reset( $wp_filter[ $hook ] );

    do {
        foreach ( (array) current( $wp_filter[ $hook ] ) as $the_ ) {
            if ( ! is_null( $the_['function'] ) ) {
                call_user_func_array( $the_['function'], $args );
            }
        }
    } while ( next( $wp_filter[ $hook ] ) !== false );
}

• reset( $wp_filter[ $hook ] );： 将 $wp_filter[ $hook ] 数组的内部指针重置到第一个元素。

• do { ... } while ( next( $wp_filter[ $hook ] ) !== false );： 这是一个循环，用于遍历所有挂在 $hook 上的函数。

• foreach ( (array) current( $wp_filter[ $hook ] ) as $the_ ) { ... }： 对于每个函数，从 $wp_filter 数组中取出它的信息（包括函数名、优先级等）。

• call_user_func_array( $the_['function'], $args );： 这是最核心的一行代码。 它使用 call_user_func_array() 函数来调用挂在钩子上的函数，并且将 $args 数组作为参数传递给这个函数。 因为我们传递的是引用数组，所以，钩子函数内部对 $args 数组的修改，会直接影响到原始变量。

5. 引用传递的实际应用场景

那么，在什么情况下，我们需要使用 do_action_ref_array() 呢？ 答案是：当我们需要在钩子函数内部修改参数的值，并且希望这些修改能够影响到原始变量时。

以下是一些常见的应用场景：

• 数据验证和清理： 假设我们有一个表单，用户可以输入一些数据。 在保存数据之前，我们需要对这些数据进行验证和清理。 我们可以使用 do_action_ref_array() 来创建一个钩子，让不同的插件可以对数据进行验证和清理。
• 内容过滤： 假设我们需要对文章的内容进行过滤，比如删除敏感词汇、添加链接等。 我们可以使用 do_action_ref_array() 来创建一个钩子，让不同的插件可以对文章内容进行过滤。
• 购物车价格计算：假设我们需要计算购物车的总价格，不同的插件可以根据用户身份，优惠券等条件修改购物车商品的价格。

6. 代码示例：修改文章标题

让我们通过一个具体的例子来说明 do_action_ref_array() 的用法。 假设我们想要创建一个钩子，让不同的插件可以修改文章的标题。

首先，我们在发布文章之前，触发一个 action 钩子：

$title = $_POST['post_title']; // 从表单中获取文章标题
do_action_ref_array( 'modify_post_title', array( &$title ) ); // 注意：引用传递
update_post_meta( $post_id, 'post_title', $title ); // 保存修改后的文章标题

然后，我们可以创建一个插件，挂在这个钩子上，修改文章的标题：

add_action( 'modify_post_title', 'my_plugin_modify_post_title' );

function my_plugin_modify_post_title( &$title ) { // 注意：引用传递
    $title = '【' . date( 'Y-m-d' ) . '】' . $title; // 在标题前面添加日期
}

在这个例子中，my_plugin_modify_post_title() 函数接收一个引用参数 $title。 它在标题前面添加了日期，并且修改了 $title 的值。 因为我们使用的是引用传递，所以，原始变量 $title 的值也会被修改。

7. do_action() vs do_action_ref_array()：选择哪个？

那么，在实际开发中，我们应该选择 do_action() 还是 do_action_ref_array() 呢？

特性	do_action()	do_action_ref_array()
参数传递方式	值传递	引用传递
是否修改原始变量	否	是
适用场景	不需要修改参数	需要修改参数

总的来说，如果你的钩子函数只需要读取参数的值，而不需要修改它们，那么使用 do_action() 就足够了。 但是，如果你的钩子函数需要修改参数的值，并且希望这些修改能够影响到原始变量，那么就必须使用 do_action_ref_array()。

8. 注意事项：谨慎使用引用传递

虽然引用传递非常强大，但是也需要谨慎使用。 因为它会直接修改原始变量的值，如果不小心，可能会导致一些意想不到的问题。

在使用 do_action_ref_array() 之前，一定要仔细考虑清楚，是否真的需要修改原始变量的值。 如果仅仅是需要读取参数的值，那么使用 do_action() 就可以了。

此外，还要注意代码的可读性和可维护性。 在使用引用传递时，最好在代码中添加注释，说明哪些参数会被修改，以及修改的目的。

9. 总结

do_action_ref_array() 是 WordPress 中一个非常有用的函数，它允许我们通过引用传递参数给 action 钩子。 掌握了它的用法，可以让我们更好地控制 WordPress 的行为，实现更灵活、更强大的功能。

希望今天的讲解能够帮助大家更好地理解 do_action_ref_array() 函数。 记住，技术就像一把双刃剑，用得好能披荆斩棘，用不好可能伤到自己。 谨慎使用引用传递，让你的代码更加健壮！

今天的分享就到这里，谢谢大家！ 如果有任何问题，欢迎随时提问。