剖析 WordPress `do_action_ref_array()` 函数的源码：如何通过引用传递参数给 `action` 钩子。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

咳咳，麦克风试音… 1, 2, 3… 好的，各位观众老爷们，今天咱们来聊聊 WordPress 里面一个相当有趣，但有时候又让人有点摸不着头脑的函数：do_action_ref_array()。

咱们先打个招呼，我是今天的讲师，江湖人称“代码老中医”，专治各种奇奇怪怪的代码疑难杂症。今天咱们要解剖的这玩意儿，说白了，就是 WordPress 里面用来触发“动作” (action) 钩子的一个加强版。它最大的特点，也是最容易让人困惑的地方，就是它能通过“引用”的方式传递参数给挂载到 action 上的函数。

什么是 Action 钩子？先来个热身

在深入 do_action_ref_array() 之前，咱们先简单回顾一下 WordPress 的 action 钩子。你可以把它想象成代码中的“事件触发器”。WordPress 在执行代码的过程中，会在某些关键点抛出一个“事件”，也就是触发一个 action 钩子。你可以在这些钩子上“挂载”你自己的函数，让它们在特定时刻执行。

比如，wp_head 这个 action 钩子，会在 HTML 的 <head> 标签中被触发。你可以挂载一些函数到 wp_head 上，用来添加 CSS、JavaScript 代码，或者执行其他需要在 head 标签中进行的操作。

最常用的触发 action 钩子的函数是 do_action()。它的基本用法是这样的：

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

这里，'my_custom_action' 是 action 钩子的名称，$arg1 和 $arg2 是传递给挂载到这个钩子上的函数的参数。

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

现在，重点来了！do_action_ref_array() 和 do_action() 的主要区别在于，前者使用“引用”来传递参数，而不是“值传递”。啥意思呢？

简单来说，值传递就是把变量的值复制一份，传递给函数。函数内部对参数的修改不会影响到原始变量。而引用传递，是把变量的“地址”传递给函数。函数内部对参数的修改会直接影响到原始变量。

do_action_ref_array() 的语法是这样的：

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

注意看，这里传递的参数不是像 do_action() 那样直接传递，而是放到一个数组里，并且每个参数前面都有一个 & 符号。这个 & 符号就是“引用”的标志。

为什么需要引用传递？

你可能会问，为什么要这么麻烦，搞个引用传递呢？这样做的好处是：

修改参数： 挂载到 action 钩子上的函数可以直接修改传递给它的参数。这在某些场景下非常有用，比如你需要动态地修改某个变量的值，然后让后续的函数使用修改后的值。
性能优化： 对于大型对象或者数组，引用传递可以避免不必要的内存复制，提高性能。

代码示例：实战演练

光说不练假把式，咱们来个实际的例子。假设我们需要创建一个 action 钩子，允许挂载的函数修改传递给它的字符串。

<?php

// 定义一个字符串变量
$my_string = 'Hello, world!';

// 定义一个函数，用于修改字符串
function modify_string( &$string ) {
  $string = 'Modified: ' . $string;
}

// 挂载函数到 action 钩子
add_action( 'my_string_action', 'modify_string' );

// 触发 action 钩子
do_action_ref_array( 'my_string_action', array( &$my_string ) );

// 输出修改后的字符串
echo $my_string; // 输出：Modified: Hello, world!

?>

在这个例子中：

我们定义了一个字符串变量 $my_string。
我们定义了一个函数 modify_string()，它接受一个引用传递的字符串参数 $string，并在字符串前面加上 "Modified: "。
我们使用 add_action() 函数将 modify_string() 函数挂载到 my_string_action 钩子上。
我们使用 do_action_ref_array() 函数触发 my_string_action 钩子，并将 $my_string 变量的引用传递给它。
最后，我们输出 $my_string 变量的值，可以看到它已经被 modify_string() 函数修改了。

如果我们将 do_action_ref_array() 替换为 do_action()，代码会变成这样：

<?php

// 定义一个字符串变量
$my_string = 'Hello, world!';

// 定义一个函数，用于修改字符串
function modify_string( $string ) { // 注意这里没有 & 符号了
  $string = 'Modified: ' . $string;
}

// 挂载函数到 action 钩子
add_action( 'my_string_action', 'modify_string' );

// 触发 action 钩子
do_action( 'my_string_action', $my_string );

// 输出修改后的字符串
echo $my_string; // 输出：Hello, world!

?>

可以看到，这次输出的 $my_string 仍然是原始值 "Hello, world!"，因为 modify_string() 函数接收到的是 $my_string 的一个副本，而不是引用。

源码剖析：深入 do_action_ref_array() 的内部

为了更深入地理解 do_action_ref_array() 的工作原理，咱们来扒一扒它的源码。它的源码位于 wp-includes/plugin.php 文件中。

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 ] = 0;
    }

    ++$wp_actions[ $hook_name ];

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

    $wp_current_filter[] = $hook_name;

    $args = (array) $args; // 确保 $args 是一个数组

    $priority = current( $wp_filter[ $hook_name ] );

    if ( ! $priority ) {
        array_shift( $wp_filter[ $hook_name ] );
        return;
    }

    reset( $wp_filter[ $hook_name ][ $priority ] );

    do {
        foreach ( (array) current( $wp_filter[ $hook_name ][ $priority ] ) as $the_ ) {
            if ( ! is_null( $the_['function'] ) ) {
                call_user_func_array( $the_['function'], $args ); // 关键！
            }
        }
    } while ( next( $wp_filter[ $hook_name ][ $priority ] ) !== false );

    array_pop( $wp_current_filter );
}

咱们一行一行地来解读一下：

global $wp_filter, $wp_actions, $wp_current_filter;: 声明全局变量。$wp_filter 是一个多维数组，存储了所有 action 和 filter 钩子的信息，包括挂载的函数、优先级等。$wp_actions 用于记录 action 钩子被触发的次数。$wp_current_filter 用于记录当前正在执行的 action 或 filter 钩子的名称，用于防止循环调用。
if ( ! isset( $wp_actions[ $hook_name ] ) ) { ... }: 如果 $wp_actions 中还没有 $hook_name 的记录，就初始化它。
++$wp_actions[ $hook_name ];: 将 $hook_name 对应的触发次数加 1。
if ( ! isset( $wp_filter[ $hook_name ] ) ) { return; }: 如果 $wp_filter 中没有 $hook_name 的记录，说明没有函数挂载到这个钩子上，直接返回。
$wp_current_filter[] = $hook_name;: 将 $hook_name 添加到 $wp_current_filter 数组中，表示当前正在执行这个 action 钩子。
$args = (array) $args;: 强制将 $args 转换为数组，确保后续操作的正确性。
$priority = current( $wp_filter[ $hook_name ] );: 获取当前优先级。
if ( ! $priority ) { ... }: 如果没有优先级，就移除并返回。
reset( $wp_filter[ $hook_name ][ $priority ] );: 重置 $wp_filter[ $hook_name ][ $priority ] 数组的指针，以便从第一个函数开始遍历。
do { ... } while ( next( $wp_filter[ $hook_name ][ $priority ] ) !== false );: 循环遍历所有挂载到 $hook_name 上的函数，按照优先级顺序执行。
foreach ( (array) current( $wp_filter[ $hook_name ][ $priority ] ) as $the_ ) { ... }: 循环遍历当前优先级下的所有函数。
if ( ! is_null( $the_['function'] ) ) { call_user_func_array( $the_['function'], $args ); }: 关键的一行！ 使用 call_user_func_array() 函数调用挂载的函数。 call_user_func_array() 函数可以接受一个函数名和一个参数数组，然后调用该函数，并将参数数组传递给它。由于 $args 数组包含的是参数的引用，所以挂载的函数可以直接修改原始变量的值。
array_pop( $wp_current_filter );: 将 $hook_name 从 $wp_current_filter 数组中移除，表示这个 action 钩子已经执行完毕。

call_user_func_array()：幕后英雄

call_user_func_array() 是 PHP 的一个内置函数，它的作用是动态调用函数，并将一个数组作为参数传递给它。

mixed call_user_func_array ( callable $callback , array $param_arr )

在这个函数中，$callback 是要调用的函数名，$param_arr 是一个包含参数的数组。关键在于，$param_arr 数组中的元素会按照顺序传递给 $callback 函数的参数。

do_action_ref_array() 的适用场景

哪些情况下，我们应该选择 do_action_ref_array() 而不是 do_action() 呢？

需要修改参数： 如果你的 action 钩子需要允许挂载的函数修改传递给它的参数，那么 do_action_ref_array() 是不二之选。
性能优化： 如果传递给 action 钩子的参数是大型对象或数组，并且你不需要复制这些对象或数组，那么 do_action_ref_array() 可以提高性能。
与其他代码的兼容性： 有些 WordPress 插件或主题可能会依赖于 do_action_ref_array() 来传递参数，为了保持兼容性，你也应该使用它。

注意事项

在使用 do_action_ref_array() 时，需要注意以下几点：

确保参数是引用： 传递给 do_action_ref_array() 的参数必须是引用，否则修改将无效。
小心修改参数： 由于挂载的函数可以直接修改参数，因此需要谨慎操作，避免意外的修改导致程序出错。
文档说明： 如果你的插件或主题使用了 do_action_ref_array()，务必在文档中说明清楚，以便其他开发者了解如何正确地使用你的 action 钩子。

总结：

do_action_ref_array() 是 WordPress 中一个强大而灵活的函数，它允许通过引用传递参数给 action 钩子，从而实现更高级的功能。理解它的工作原理，可以帮助你更好地利用 WordPress 的 action 钩子机制，开发出更高效、更灵活的插件和主题。

表格总结：do_action() vs do_action_ref_array()

特性	`do_action()`	`do_action_ref_array()`
参数传递方式	值传递	引用传递
是否可以修改参数	否	是
适用场景	不需要修改参数	需要修改参数，或优化性能
语法	`do_action('hook', $arg1, $arg2);`	`do_action_ref_array('hook', array(&$arg1, &$arg2));`

好了，今天的讲座就到这里。希望大家通过今天的学习，能够对 do_action_ref_array() 有更深入的理解。如果大家还有什么疑问，欢迎随时提问。咱们下次再见！

发表回复 取消回复

发表回复取消回复