发布于 由admin

阐述 WordPress `add_action()` 和 `add_filter()` 中的 `$priority` 参数源码：其如何影响钩子函数的执行顺序。

WordPress 钩子：add_action() 和 add_filter() 的 $priority 参数深度剖析 (讲座模式)

嘿！大家好，欢迎来到今天的 WordPress 钩子技术讲座。今天我们来聊聊 add_action() 和 add_filter() 这两个兄弟函数中，一个非常关键但又经常被忽略的参数：$priority。

先别急着打哈欠，我知道“优先级”听起来很枯燥，但它可是决定你的代码在 WordPress 世界里能不能按你期望的方式执行的关键。想象一下，如果没有优先级，所有人的代码都挤在一起，谁先执行谁后执行，那还不得乱套？

所以，今天我们就来扒一扒 $priority 的源码，看看它到底是怎么影响钩子函数的执行顺序的。保证让你听完之后，对 WordPress 的钩子机制有更深刻的理解，写出更健壮、更可控的代码。

1. 钩子机制：WordPress 的神经系统

在深入 $priority 之前，我们先简单回顾一下 WordPress 的钩子机制。你可以把它想象成 WordPress 的神经系统，它允许你 "hook" (钩住) 到 WordPress 的核心代码中，在你想要的地方执行你自己的代码。

  • Actions (动作): 允许你在 WordPress 运行的特定时刻执行代码。比如，在文章发布后发送邮件，或者在页面加载之前添加一些自定义 CSS。
  • Filters (过滤器): 允许你修改 WordPress 的数据。比如，修改文章标题，或者过滤评论内容。

add_action() 和 add_filter() 就是你往这个神经系统里注册钩子的工具。

2. add_action() 和 add_filter()：钩子的注册官

这两个函数长得很像，用法也很相似，区别在于 add_action() 注册的是动作，而 add_filter() 注册的是过滤器。

它们的通用结构如下：

add_action( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 );
add_filter( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 );
  • $tag: 钩子的名称，也就是你想 "hook" 到哪个位置。比如 'wp_head' (在 <head> 标签中)，'the_content' (文章内容)。
  • $function_to_add: 你想执行的函数 (你的代码)。
  • $priority: 重点来了！ 钩子函数的优先级，决定了它在同一钩子上执行的顺序。 默认值是 10。
  • $accepted_args: 你的函数接收的参数数量。

3. $priority：执行顺序的指挥棒

$priority 参数是一个整数，它的值越小，优先级越高，也就是说，它会越早被执行。

重点：

  • 数值越小，优先级越高 (越早执行)。
  • 数值越大，优先级越低 (越晚执行)。
  • 如果多个钩子函数的 $priority 值相同，它们会按照注册的顺序执行 (先注册的先执行)。

现在，让我们用一些例子来说明：

// 注册一个函数，优先级为 1，最先执行
add_action( 'wp_head', 'my_function_1', 1 );

// 注册一个函数，优先级为 5，第二个执行
add_action( 'wp_head', 'my_function_2', 5 );

// 注册一个函数，优先级为 10 (默认值)，第三个执行
add_action( 'wp_head', 'my_function_3' );

// 注册一个函数，优先级为 10，第四个执行 (与 my_function_3 优先级相同，按照注册顺序)
add_action( 'wp_head', 'my_function_4', 10 );

// 注册一个函数，优先级为 20，最后执行
add_action( 'wp_head', 'my_function_5', 20 );

在这个例子中，wp_head 钩子上的函数执行顺序是：

  1. my_function_1 (优先级 1)
  2. my_function_2 (优先级 5)
  3. my_function_3 (优先级 10)
  4. my_function_4 (优先级 10)
  5. my_function_5 (优先级 20)

4. 源码剖析：$priority 的幕后推手

现在，让我们深入 WordPress 的源码，看看 $priority 到底是如何影响钩子函数的执行顺序的。

为了方便理解，我们只关注核心部分的代码。以下代码来自 wp-includes/plugin.php 文件。

4.1 add_filter() 和 add_action() 的本质：WP_Hook 类

add_filter() 和 add_action() 最终都会调用 WP_Hook 类的 add_filter() 方法。 WP_Hook 类负责管理和执行钩子函数。

// wp-includes/plugin.php

/**
 * Adds a function to a specific filter hook.
 *
 * @since 0.71
 *
 * @param string   $tag             The name of the filter to hook the $function_to_add to.
 * @param callable $function_to_add The callback to be run when the filter is applied.
 * @param int      $priority        Optional. Used to specify the order in which the functions
 *                                    associated with a particular action are executed.
 *                                    Lower numbers correspond with earlier execution,
 *                                    and functions with the same priority are executed
 *                                    in the order in which they were added to the action.
 *                                    Default 10.
 * @param int      $accepted_args   Optional. The number of arguments the function accepts.
 *                                    Default 1.
 * @return true
 */
function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
    global $wp_filter;

    if ( ! ( $wp_filter[ $tag ] instanceof WP_Hook ) ) {
        $wp_filter[ $tag ] = new WP_Hook();
    }

    $wp_filter[ $tag ]->add_filter( $tag, $function_to_add, $priority, $accepted_args );

    return true;
}

/**
 * Adds a function to a specific action hook.
 *
 * @since 1.2.0
 *
 * @param string   $tag             The name of the action to which the $function_to_add is hooked.
 * @param callable $function_to_add The name of the function you wish to be called.
 * @param int      $priority        Optional. Used to specify the order in which the functions
 *                                    associated with a particular action are executed.
 *                                    Lower numbers correspond with earlier execution,
 *                                    and functions with the same priority are executed
 *                                    in the order in which they were added to the action.
 *                                    Default 10.
 * @param int      $accepted_args   Optional. The number of arguments the function accepts.
 *                                    Default 1.
 * @return true
 */
function add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
    return add_filter( $tag, $function_to_add, $priority, $accepted_args );
}

可以看到，add_action 实际上就是 add_filter 的一个别名。 它们都调用了 $wp_filter[$tag]->add_filter()。

4.2 WP_Hook::add_filter()：存储钩子信息

WP_Hook 类的 add_filter() 方法负责将钩子函数的信息 (包括函数名、优先级、参数数量等) 存储起来。

// wp-includes/class-wp-hook.php

    /**
     * Add a filter to the collection.
     *
     * @since 4.7.0
     *
     * @param string   $tag             Hook name.
     * @param callable $function_to_add Function to be called when the filter is applied.
     * @param int      $priority        Priority of the function.
     * @param int      $accepted_args   Number of arguments accepted by the function.
     */
    public function add_filter( $tag, $function_to_add, $priority, $accepted_args ) {
        $idx = _wp_filter_build_unique_id( $tag, $function_to_add, $priority );

        $priority_existed = isset( $this->callbacks[ $priority ] );

        $this->callbacks[ $priority ][ $idx ] = array(
            'function'      => $function_to_add,
            'accepted_args' => $accepted_args,
        );

        // Need to resort the priority queue?
        if ( ! $priority_existed && isset( $this->merged_filters[ $tag ] ) ) {
            unset( $this->merged_filters[ $tag ] );
        }
    }

这段代码的关键在于 $this->callbacks 数组。它是一个二维数组，第一维是优先级 ($priority)，第二维是钩子函数的唯一 ID ($idx)。

简单来说，add_filter() 会把你的钩子函数的信息，按照优先级，存储到 $this->callbacks 数组里。

数据结构:

$this->callbacks 数组的结构大致如下:

$this->callbacks = [
    1 => [ // 优先级 1
        'unique_id_1' => [ 'function' => 'my_function_1', 'accepted_args' => 1 ],
    ],
    5 => [ // 优先级 5
        'unique_id_2' => [ 'function' => 'my_function_2', 'accepted_args' => 1 ],
    ],
    10 => [ // 优先级 10
        'unique_id_3' => [ 'function' => 'my_function_3', 'accepted_args' => 1 ],
        'unique_id_4' => [ 'function' => 'my_function_4', 'accepted_args' => 1 ],
    ],
    20 => [ // 优先级 20
        'unique_id_5' => [ 'function' => 'my_function_5', 'accepted_args' => 1 ],
    ],
];

4.3 WP_Hook::apply_filters() 和 WP_Hook::do_action()：执行钩子函数

当 WordPress 运行到触发钩子的位置时，会调用 apply_filters() (对于过滤器) 或 do_action() (对于动作) 来执行注册到该钩子上的函数。

这两个函数最终都会调用 WP_Hook 类的 apply_filters() 方法。

// wp-includes/class-wp-hook.php

    /**
     * Execute all of the functions attached to a given filter hook.
     *
     * @since 4.7.0
     *
     * @param string $tag    The name of the filter hook.
     * @param mixed  $value  The value on which the filters hooked to `$tag` are applied.
     * @param array  $args   Optional. Additional arguments to pass to the functions hooked to `$tag`.
     *                       Default empty array.
     * @return mixed The filtered value after all hooked functions are applied to it.
     */
    public function apply_filters( $tag, $value, $args ) {
        $this->current_filter[] = $tag;

        // Sort.
        if ( ! isset( $this->merged_filters[ $tag ] ) ) {
            ksort( $this->callbacks );
            $this->merged_filters[ $tag ] = true;
        }

        $args = array_slice( func_get_args(), 1 );

        // Do 'all' actions first.
        if ( isset( $this->callbacks['all'] ) ) {
            $this->do_all_hook( $args );
        }

        if ( ! isset( $this->callbacks[ $tag ] ) ) {
            array_pop( $this->current_filter );
            return $value;
        }

        $this->iterations[ $this->recursion_depth ] = $this->iterations[ $this->recursion_depth ] ?? 0;
        $this->recursion_depth++;

        foreach ( (array) $this->callbacks[ $tag ] as $priority => $functions ) {
            foreach ( $functions as $function ) {
                $this->iterations[ $this->recursion_depth ]++;

                $args[0] = $value;
                $value = call_user_func_array( $function['function'], array_slice( $args, 0, (int) $function['accepted_args'] ) );
            }
        }

        $this->recursion_depth--;
        array_pop( $this->current_filter );

        return $value;
    }

这段代码的关键在于：

  1. ksort( $this->callbacks ): 在执行钩子函数之前，会先对 $this->callbacks 数组按照键名 (也就是优先级) 进行升序排序。 这就是为什么优先级数值越小，越先执行的原因。
  2. foreach ( (array) $this->callbacks[ $tag ] as $priority => $functions ): 然后，它会遍历 $this->callbacks 数组，按照优先级从小到大的顺序，依次执行每个优先级下的所有钩子函数。
  3. foreach ( $functions as $function ): 如果同一优先级下有多个钩子函数，它们会按照注册的顺序执行。
  4. call_user_func_array( $function['function'], array_slice( $args, 0, (int) $function['accepted_args'] ) ): 最后，它会调用钩子函数，并传递相应的参数。

总结:

$priority 参数通过以下方式影响钩子函数的执行顺序：

  1. add_filter() 将钩子函数的信息按照优先级存储到 $this->callbacks 数组中。
  2. apply_filters() 在执行钩子函数之前，先对 $this->callbacks 数组按照优先级进行升序排序。
  3. apply_filters() 按照排序后的顺序，依次执行每个优先级下的所有钩子函数。
  4. 同一优先级下的钩子函数，按照注册的顺序执行。

5. $priority 的最佳实践：避免冲突，保持灵活

掌握了 $priority 的工作原理之后，我们来看看如何在实际开发中使用它，才能写出更健壮、更可控的代码。

  • 避免使用过于接近的优先级： 尽量避免使用过于接近的优先级，比如 9、10、11。 这样会降低代码的灵活性，如果以后需要插入新的钩子函数，可能会遇到优先级冲突的问题。

  • 使用常量定义优先级： 为了提高代码的可读性和可维护性，可以使用常量来定义优先级。

    define( 'MY_PLUGIN_PRIORITY_EARLY', 5 );
define( 'MY_PLUGIN_PRIORITY_DEFAULT', 10 );
define( 'MY_PLUGIN_PRIORITY_LATE', 20 );

add_action( 'wp_head', 'my_function_1', MY_PLUGIN_PRIORITY_EARLY );
add_action( 'wp_head', 'my_function_2', MY_PLUGIN_PRIORITY_LATE );

  • 考虑依赖关系： 如果你的代码依赖于其他插件或主题的代码，你需要仔细考虑优先级，确保你的代码在依赖的代码之后执行。 可以使用 plugins_loaded 钩子来确保所有插件都已加载。

  • 默认值的陷阱： 默认优先级是 10。 如果你不设置优先级，你的函数可能会在很多其他函数之后执行。 这可能导致不可预测的结果。 谨慎使用默认优先级。

  • 利用较大间距： 建议使用较大的优先级间距，例如 10, 20, 30。这允许其他开发者在你的钩子之间插入他们自己的函数，而无需修改你代码的优先级。

示例：修改文章标题

假设你想修改文章标题，确保在所有其他插件修改标题之后再执行你的修改。 你可以这样做：

function my_plugin_filter_the_title( $title ) {
  // 你的修改逻辑
  return 'My Plugin: ' . $title;
}
add_filter( 'the_title', 'my_plugin_filter_the_title', 99 ); // 使用较高的优先级

这里，我们使用了优先级 99，确保我们的函数在大多数其他函数之后执行。

表格总结

概念 描述 示例
$priority 一个整数，用于确定钩子函数执行的顺序。 数值越小，优先级越高（越早执行）。 add_action( 'wp_head', 'my_function', 5 ); // 优先级 5，比默认优先级 10 的函数更早执行。
默认优先级 10. 如果未指定优先级，则使用此值。 add_action( 'wp_head', 'my_function' ); // 等同于 add_action( 'wp_head', 'my_function', 10 );
优先级相同 如果多个钩子函数的优先级相同，则按照注册的顺序执行（先注册的先执行）。 add_action( 'wp_head', 'function_a', 10 ); add_action( 'wp_head', 'function_b', 10 ); // function_a 会在 function_b 之前执行。
最佳实践 1. 避免使用过于接近的优先级。 2. 使用常量定义优先级。 3. 考虑依赖关系，确保代码在依赖的代码之后执行。 4. 谨慎使用默认优先级。 5. 利用较大间距。 define( 'MY_PRIORITY_EARLY', 5 ); add_filter( 'the_content', 'my_content_filter', MY_PRIORITY_EARLY ); // 使用常量定义优先级，提高代码可读性。
源码关键函数 WP_Hook::add_filter()：将钩子函数信息存储到 $this->callbacks 数组中，按照优先级存储。 WP_Hook::apply_filters()：在执行钩子函数之前，先对 $this->callbacks 数组按照优先级进行升序排序，然后按照排序后的顺序执行钩子函数。 –
应用场景 调整插件或主题功能的执行顺序。例如，确保你的插件在其他插件之后修改文章内容，或者在其他插件之前加载 CSS 文件。 –
潜在问题 优先级冲突：如果多个插件使用相同的优先级，可能会导致执行顺序混乱，影响插件的功能。 优先级设置不当：如果优先级设置得太高或太低，可能会导致代码无法正常执行，或者影响其他插件的功能。 –

6. 总结

好了，今天的讲座就到这里。希望通过今天的讲解，你对 WordPress 的 add_action() 和 add_filter() 函数的 $priority 参数有了更深入的理解。

记住，$priority 是一个强大的工具，可以让你更好地控制你的代码在 WordPress 世界里的行为。 合理地使用它，可以避免冲突，提高代码的灵活性和可维护性。

下次再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注