WordPress自定义钩子优先级排序机制与回调依赖解析的源码实现分析

WordPress 自定义钩子优先级排序机制与回调依赖解析的源码实现分析

大家好，今天我们来深入探讨 WordPress 中自定义钩子的优先级排序机制以及回调函数的依赖解析的源码实现。理解这些机制对于开发高效、健壮的 WordPress 插件和主题至关重要。

1. 钩子系统概述

WordPress 的钩子系统是其核心扩展机制，允许开发者在 WordPress 的核心代码执行过程中插入自定义代码，而无需修改核心代码本身。钩子分为两种类型：动作（Actions）和过滤器（Filters）。

• Actions (动作): 允许你在特定的时间点执行自定义代码。例如，wp_footer 动作允许你在页面底部插入代码。
• Filters (过滤器): 允许你修改特定的数据。例如，the_content 过滤器允许你修改文章的内容。

钩子系统通过两个主要函数来实现：

• add_action() / add_filter(): 用于注册回调函数到指定的钩子上。
• do_action() / apply_filters(): 用于触发钩子，执行所有注册的回调函数。

2. 优先级排序机制

WordPress 允许为回调函数指定优先级，从而控制它们在钩子被触发时的执行顺序。优先级是一个整数，数值越小，优先级越高，回调函数越先执行。默认优先级是 10。

2.1 add_action() / add_filter() 函数源码分析

让我们看看 add_action() 函数（add_filter() 函数的实现方式类似）的源码，了解优先级是如何被处理的。

function add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
    return add_filter( $tag, $function_to_add, $priority, $accepted_args );
}

function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
    global $wp_filter, $merged_filters, $wp_current_filter;

    $idx = _wp_filter_build_unique_id( $tag, $function_to_add, $priority );

    $wp_filter[ $tag ][ $priority ][ $idx ] = array(
        'function'      => $function_to_add,
        'accepted_args' => $accepted_args
    );

    unset( $merged_filters[ $tag ] );

    if ( doing_filter( $tag ) ) {
        global $wp_actions;

        if ( isset( $wp_actions[ $tag ] ) ) {
            ++$wp_actions[ $tag ];
        }

        /**
         * Fires the given filter.
         *
         * Passing parameters to the dynamic filter hook will trigger an undefined
         * variable notice.
         *
         * @since 2.5.0
         *
         * @param mixed $value The value to filter.
         */
        do_action( 'wp_filter_add_filter', $tag, $function_to_add, $priority, $accepted_args );

        // Ensure we pass the current filter as part of the context.
        array_unshift( $wp_current_filter, $tag );

        $args = array();
        if ( isset( $wp_filter[ $tag ][ $priority ] ) ) {
            foreach ( $wp_filter[ $tag ][ $priority ] as $filter ) {
                if ( ! is_null( $filter['function'] ) ) {
                    $args[] = $filter['function'];
                }
            }
        }

        array_shift( $wp_current_filter );
    }

    return true;
}

关键部分：

• global $wp_filter: 声明 $wp_filter 为全局变量。这个变量是一个多维数组，用于存储所有注册的钩子和它们的回调函数。
• $idx = _wp_filter_build_unique_id( $tag, $function_to_add, $priority );: 生成一个唯一 ID，用于标识每个回调函数。这个 ID 基于钩子名称、回调函数以及优先级。

• $wp_filter[ $tag ][ $priority ][ $idx ] = ...: 将回调函数的信息存储到 $wp_filter 数组中。$wp_filter 的结构如下：

  $wp_filter = array(
      'hook_name' => array(
          priority_1 => array(
              unique_id_1 => array(
                  'function' => 'callback_function_1',
                  'accepted_args' => number_of_arguments
              ),
              unique_id_2 => array(
                  'function' => 'callback_function_2',
                  'accepted_args' => number_of_arguments
              ),
          ),
          priority_2 => array(
              unique_id_3 => array(
                  'function' => 'callback_function_3',
                  'accepted_args' => number_of_arguments
              ),
          ),
      ),
  );

  可以看到，$wp_filter 是一个三维数组，第一维是钩子名称，第二维是优先级，第三维是回调函数的唯一 ID。

2.2 do_action() / apply_filters() 函数源码分析

现在，让我们看看 do_action() 函数（apply_filters() 函数的实现方式类似）的源码，了解回调函数是如何被执行的。

function do_action( $tag, ...$arg ) {
    global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;

    $wp_current_filter[] = $tag;

    // Do 'all' actions first.
    if ( isset( $wp_filter['all'] ) ) {
        _wp_call_all_hook( $arg );
    }

    if ( isset( $wp_filter[ $tag ] ) ) {
        _wp_call_all_hook( $arg, $tag );
    }

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

    /**
     * Fires functions attached to a specific action hook.
     *
     * The dynamic portion of the hook name, `$tag`, refers to the name
     * of the action hook.
     *
     * @since 3.0.0
     *
     * @param mixed ...$arg The list of arguments to pass to the functions.
     */
    do_action( "{$tag}", ...$arg );

    array_pop( $wp_current_filter );
}

function apply_filters( $tag, $value, ...$args ) {
    global $wp_filter, $merged_filters, $wp_current_filter;

    $wp_current_filter[] = $tag;

    $targs = func_get_args();
    $value = array_shift( $targs );
    $args  = array_slice( $targs, 1 );

    // Do 'all' actions first.
    if ( isset( $wp_filter['all'] ) ) {
        _wp_call_all_hook( array( $value, ...$args ) );
    }

    if ( isset( $wp_filter[ $tag ] ) ) {
        $value = _wp_call_all_hook( array( $value, ...$args ), $tag );
    }

    array_pop( $wp_current_filter );

    return $value;
}

关键部分（以 apply_filters 为例）：

• global $wp_filter: 再次声明 $wp_filter 为全局变量，以便访问存储的回调函数信息。
• if ( isset( $wp_filter[ $tag ] ) ): 检查是否存在指定钩子的回调函数。
• $value = _wp_call_all_hook( array( $value, ...$args ), $tag );: 调用 _wp_call_all_hook 执行所有注册的回调函数。

现在我们来看下_wp_call_all_hook

/**
 * Executes functions hooked on to a filter.
 *
 * @since 5.1.0
 * @access private
 *
 * @global array $wp_filter Stores all of the filters.
 *
 * @param array  $args The array of arguments passed to apply_filters().
 * @param string $tag  The name of the filter hook.
 * @return mixed Initial `$args` passed to apply_filters().
 */
function _wp_call_all_hook( $args, $tag = '' ) {
    global $wp_filter;

    if ( ! $tag ) {
        $priority_arr = array( $wp_filter['all'] );
    } else {
        $priority_arr = $wp_filter[ $tag ];
    }

    if ( ! $priority_arr ) {
        return $args[0];
    }

    ksort( $priority_arr );

    foreach ( $priority_arr as $priority => $functions ) {
        foreach ( $functions as $function ) {
            $func = $function['function'];
            $accepted_args = $function['accepted_args'];

            if ( is_callable( $func ) ) {
                $the_args = array_slice( $args, 0, (int) $accepted_args );
                $value = call_user_func_array( $func, $the_args );

                if ( 'all' === $tag ) {
                    continue;
                }

                $args[0] = $value;
            }
        }
    }

    return $args[0];
}

关键部分：

• ksort( $priority_arr );: 对 $priority_arr 数组（包含所有优先级及其对应的回调函数）进行键排序。由于 $priority_arr 的键是优先级，因此 ksort() 函数会按照优先级从小到大（即从高到低）的顺序排列优先级。
• foreach ( $priority_arr as $priority => $functions ): 遍历排序后的优先级数组，按照优先级顺序执行回调函数。
• foreach ( $functions as $function ): 遍历每个优先级下的所有回调函数
• call_user_func_array( $func, $the_args );: 调用回调函数，并将参数传递给它。

总结：

add_action() / add_filter() 函数将回调函数及其优先级信息存储到全局 $wp_filter 数组中。do_action() / apply_filters() 函数从 $wp_filter 数组中检索回调函数，并按照优先级顺序执行它们。ksort() 函数保证了回调函数按照优先级从小到大（即从高到低）的顺序执行。

2.3 优先级示例

假设我们有以下代码：

add_action( 'my_hook', 'my_function_1', 10 );
add_action( 'my_hook', 'my_function_2', 5 );
add_action( 'my_hook', 'my_function_3', 15 );

function my_function_1() {
    echo "Function 1n";
}

function my_function_2() {
    echo "Function 2n";
}

function my_function_3() {
    echo "Function 3n";
}

do_action( 'my_hook' );

执行结果将会是：

Function 2
Function 1
Function 3

因为 my_function_2 的优先级最高（5），my_function_1 的优先级次之（10），my_function_3 的优先级最低（15）。

3. 回调依赖解析

WordPress 钩子系统本身不提供直接的依赖解析机制，即无法声明某个回调函数必须在另一个回调函数之后执行。然而，我们可以通过一些技巧来实现类似的功能。

3.1 使用优先级进行控制

最简单的方法是使用优先级。如果希望某个回调函数在另一个回调函数之后执行，可以为其设置一个较低的优先级。但是，这种方法存在局限性，因为它依赖于对其他回调函数的优先级的了解。如果其他回调函数的优先级发生变化，可能会导致依赖关系失效。

3.2 使用全局变量或类属性

另一种方法是使用全局变量或类属性来存储回调函数执行的状态。后面的回调函数可以检查这些变量或属性，以确定依赖的回调函数是否已经执行。

示例：

global $my_plugin_data;
$my_plugin_data['function_1_executed'] = false;

add_action( 'my_hook', 'my_function_1', 10 );
add_action( 'my_hook', 'my_function_2', 20 );

function my_function_1() {
    global $my_plugin_data;
    echo "Function 1n";
    $my_plugin_data['function_1_executed'] = true;
}

function my_function_2() {
    global $my_plugin_data;
    if ( ! $my_plugin_data['function_1_executed'] ) {
        // Function 1 尚未执行，不执行 Function 2，或者执行一些错误处理
        echo "Function 2 cannot be executed because Function 1 has not been executed yet.n";
        return;
    }
    echo "Function 2n";
}

do_action( 'my_hook' );

在这个例子中，my_function_2 检查 $my_plugin_data['function_1_executed'] 变量，以确定 my_function_1 是否已经执行。如果 my_function_1 尚未执行，my_function_2 将不会执行。

3.3 使用类和方法

使用类和方法可以更好地组织代码，并提供更清晰的依赖关系。

示例：

class My_Plugin {
    private $function_1_executed = false;

    public function __construct() {
        add_action( 'my_hook', array( $this, 'my_function_1' ), 10 );
        add_action( 'my_hook', array( $this, 'my_function_2' ), 20 );
    }

    public function my_function_1() {
        echo "Function 1n";
        $this->function_1_executed = true;
    }

    public function my_function_2() {
        if ( ! $this->function_1_executed ) {
            echo "Function 2 cannot be executed because Function 1 has not been executed yet.n";
            return;
        }
        echo "Function 2n";
    }
}

$my_plugin = new My_Plugin();
do_action( 'my_hook' );

这个例子中，My_Plugin 类封装了两个回调函数，并使用 $function_1_executed 属性来跟踪 my_function_1 的执行状态。

3.4 使用Hook 内部的参数传递

在Filter类型的Hook中，可以利用参数传递来传递状态。

示例:

add_filter( 'my_filter', 'my_function_1', 10, 1 );
add_filter( 'my_filter', 'my_function_2', 20, 1 );

function my_function_1( $value ) {
    echo "Function 1n";
    return $value . " - Function 1";
}

function my_function_2( $value ) {
    if (strpos($value, "Function 1") === false) {
        echo "Function 2 cannot be executed because Function 1 has not been executed yet.n";
        return $value;
    }
    echo "Function 2n";
    return $value . " - Function 2";
}

$result = apply_filters( 'my_filter', 'Initial Value' );
echo "Result: " . $result . "n";

这个例子中，my_function_1 修改了传递给 my_filter 的值，并且 my_function_2 检查这个值是否包含 Function 1，如果包含，则执行，否则不执行。

总结：

虽然 WordPress 钩子系统本身不提供直接的依赖解析机制，但我们可以使用优先级、全局变量/类属性、类和方法等技巧来实现类似的功能。选择哪种方法取决于具体的应用场景和代码复杂性。

4. 优化钩子性能

大量使用钩子可能会影响 WordPress 的性能。以下是一些优化钩子性能的技巧：

• 避免不必要的钩子： 只在必要时才使用钩子。
• 使用适当的优先级： 避免将所有回调函数都设置为相同的优先级，以便 WordPress 可以更有效地排序和执行它们。
• 移除不再需要的钩子： 使用 remove_action() / remove_filter() 函数移除不再需要的钩子。
• 使用缓存： 如果回调函数的计算成本很高，可以考虑使用缓存来存储结果。
• 延迟执行： 对于一些不太重要的回调函数，可以考虑延迟执行，例如使用 WordPress 的计划任务（WP-Cron）。

4.1 remove_action() / remove_filter() 函数源码分析

function remove_action( $tag, $function_to_remove, $priority = 10 ) {
    return remove_filter( $tag, $function_to_remove, $priority );
}

function remove_filter( $tag, $function_to_remove, $priority = 10 ) {
    global $wp_filter, $merged_filters;

    $function_to_remove = _wp_filter_build_unique_id( $tag, $function_to_remove, $priority );

    $remove = false;
    if ( isset( $wp_filter[ $tag ][ $priority ][ $function_to_remove ] ) ) {
        unset( $wp_filter[ $tag ][ $priority ][ $function_to_remove ] );
        $remove = true;
        if ( empty( $wp_filter[ $tag ][ $priority ] ) ) {
            unset( $wp_filter[ $tag ][ $priority ] );
        }
        unset( $merged_filters[ $tag ] );
    }
    return $remove;
}

关键部分：

• $function_to_remove = _wp_filter_build_unique_id( $tag, $function_to_remove, $priority );: 生成要移除的回调函数的唯一 ID。
• unset( $wp_filter[ $tag ][ $priority ][ $function_to_remove ] );: 从 $wp_filter 数组中移除回调函数。

总结：

remove_action() / remove_filter() 函数允许开发者从 $wp_filter 数组中移除不再需要的钩子，从而提高性能。

5. 钩子调试技巧

调试钩子可能比较困难，因为回调函数是在 WordPress 的核心代码执行过程中被调用的。以下是一些调试钩子的技巧：

• 使用 debug_backtrace() 函数： 在回调函数中使用 debug_backtrace() 函数可以查看调用栈，了解回调函数是如何被调用的。
• 使用 error_log() 函数： 在回调函数中使用 error_log() 函数可以将调试信息写入 WordPress 的错误日志。
• 使用 WordPress 的调试模式： 启用 WordPress 的调试模式可以显示更多的错误和警告信息。在wp-config.php文件中设置WP_DEBUG为true。
• 使用插件： 有一些 WordPress 插件可以帮助你调试钩子，例如 Query Monitor。

6. 表格总结

特性	描述
钩子类型	Actions (动作) 和 Filters (过滤器)
注册函数	add_action() / add_filter()
触发函数	do_action() / apply_filters()
优先级	整数，数值越小，优先级越高，回调函数越先执行。默认优先级是 10。
$wp_filter	全局数组，用于存储所有注册的钩子和它们的回调函数。结构：$wp_filter[hook_name][priority][unique_id] = array('function' => 'callback_function', 'accepted_args' => number_of_arguments)
依赖解析	WordPress 钩子系统本身不提供直接的依赖解析机制，但可以通过优先级、全局变量/类属性、类和方法等技巧来实现类似的功能。
性能优化	避免不必要的钩子、使用适当的优先级、移除不再需要的钩子、使用缓存、延迟执行。
调试技巧	使用 debug_backtrace() 函数、使用 error_log() 函数、使用 WordPress 的调试模式、使用插件。
移除钩子	remove_action() / remove_filter()

7. 结语

深入理解WordPress的钩子系统能写出更好的代码。
灵活运用优先级和依赖解析能更好地控制代码的执行顺序。
掌握钩子的优化和调试技巧对开发更高效的程序非常有帮助。