解释 `wp_schedule_single_event()` 函数的源码，它是如何将一个定时任务添加到 `wp_options` 表的？ - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，晚上好！今天咱们来聊聊 WordPress 里面的一个重要函数，那就是 wp_schedule_single_event()。别看它名字挺长，其实干的事情很简单，就是安排一个“单次”执行的定时任务。咱们要深入源码，看看这个小家伙是怎么把任务塞进 wp_options 表里，让 WordPress 乖乖地在指定时间执行的。

一、故事的开端：定时任务的必要性

想象一下，你写了一个插件，需要在用户注册后7天发送一封欢迎邮件。你总不能天天盯着数据库，看哪个用户注册满7天了吧？这时候，定时任务就派上用场了。它可以让你设定一个时间点，让 WordPress 自动执行你预设好的代码。

WordPress 提供了多种调度事件的函数，wp_schedule_single_event() 就是其中一种，专门用于安排“一次性”的任务。

二、 wp_schedule_single_event() 函数的“真面目”

咱们先来看看 wp_schedule_single_event() 的函数定义：

function wp_schedule_single_event( int $timestamp, string $hook, array $args = array(), bool $wp_error = false ) {
    $crons = _get_cron_array(); // 获取现有的所有定时任务

    if ( isset( $crons[ $timestamp ][ $hook ] ) ) {
        foreach ( $crons[ $timestamp ][ $hook ] as $key => $scheduled_event ) {
            if ( is_array( $args ) && is_array( $scheduled_event['args'] ) ) {
                if ( $args !== $scheduled_event['args'] ) {
                    continue;
                }
            }
            return true; // 已经存在相同的事件，直接返回
        }
    }

    $key = md5( serialize( $args ) ); // 生成唯一键值

    $crons[ $timestamp ][ $hook ][ $key ] = array(
        'schedule' => false, // 单次事件，schedule 设置为 false
        'args'     => $args,   // 传递给钩子的参数
    );

    return _set_cron_array( $crons, $wp_error ); // 将更新后的 cron 数组保存回数据库
}

别被代码吓到，其实它挺友好的。咱们一行一行解释：

function wp_schedule_single_event( int $timestamp, string $hook, array $args = array(), bool $wp_error = false ):
- $timestamp: 指定任务执行的时间戳（Unix 时间戳，秒级别）。
- $hook: 指定要执行的钩子（action）。当时间到达时，WordPress 会触发这个钩子，执行你绑定到这个钩子上的函数。
- $args: 传递给钩子函数的参数，是一个数组。
- $wp_error: 指示是否返回 WP_Error 对象以指示错误。
$crons = _get_cron_array();:
- 这一步是关键。 _get_cron_array() 函数负责从 wp_options 表中读取现有的所有定时任务。这些任务都保存在一个名为 cron 的 option 里面，序列化存储。
if ( isset( $crons[ $timestamp ][ $hook ] ) ) { ... }:
- 这段代码检查是否已经存在相同时间、相同钩子、相同参数的事件。如果存在，说明这个任务已经被安排过了，直接返回 true，避免重复添加。
$key = md5( serialize( $args ) );:
- 为了确保任务的唯一性，WordPress 会根据传递给钩子的参数生成一个 MD5 散列值作为任务的唯一键。这样即使时间戳和钩子相同，只要参数不同，也会被认为是不同的任务。
$crons[ $timestamp ][ $hook ][ $key ] = array( ... );:
- 这行代码才是真正添加任务的地方。它将新的任务信息添加到 $crons 数组中。
  - 'schedule' => false: 因为是单次事件，所以 schedule 设置为 false。
  - 'args' => $args: 存储传递给钩子函数的参数。
return _set_cron_array( $crons, $wp_error );:
- 最后，_set_cron_array() 函数将更新后的 $crons 数组序列化后，保存回 wp_options 表中。

三、 _get_cron_array() 和 _set_cron_array()：幕后英雄

咱们上面提到了 _get_cron_array() 和 _set_cron_array() 这两个函数，它们是负责从 wp_options 表中读取和写入定时任务数据的“幕后英雄”。它们被划分为内部函数，名称前带有下划线。

_get_cron_array(): 从 wp_options 表中读取 cron option，并反序列化成数组。如果 cron option 不存在，则返回一个空数组。
_set_cron_array( array $crons, bool $wp_error = false ): 将 $crons 数组序列化后，更新 wp_options 表中的 cron option。如果发生错误，并且 $wp_error 为 true，则返回 WP_Error 对象。

四、 wp_options 表中的秘密

现在咱们来看看 wp_options 表里到底藏了什么秘密。 WordPress 的定时任务信息都保存在 wp_options 表中， option_name 为 cron 的 option_value 字段里。

这个 option_value 字段存储的是一个序列化的 PHP 数组。这个数组的结构大致如下：

array(
    [时间戳1] => array(
        [钩子1] => array(
            [唯一键1] => array(
                'schedule' => false, // 或 'hourly', 'daily', 'weekly' 等
                'args'     => array(),  // 传递给钩子的参数
            ),
            [唯一键2] => array(
                'schedule' => false,
                'args'     => array(
                    'user_id' => 123,
                ),
            ),
        ),
        [钩子2] => array(
            [唯一键3] => array(
                'schedule' => 'daily',
                'args'     => array(),
            ),
        ),
    ),
    [时间戳2] => array(
        // ...
    ),
);

时间戳: 任务执行的 Unix 时间戳。
钩子: 要执行的 action 的名称。
唯一键: 根据参数生成的 MD5 散列值，用于区分相同时间戳和钩子但参数不同的任务。
schedule: 任务的执行频率。对于 wp_schedule_single_event() 添加的任务，这个值始终为 false。
args: 传递给钩子函数的参数数组。

五、举个栗子：发送欢迎邮件

咱们回到一开始的例子：用户注册后7天发送欢迎邮件。假设用户注册的钩子是 user_register，我们可以这样使用 wp_schedule_single_event()：

add_action( 'user_register', 'schedule_welcome_email' );

function schedule_welcome_email( $user_id ) {
    $timestamp = time() + 7 * 24 * 60 * 60; // 7天后的时间戳
    wp_schedule_single_event( $timestamp, 'send_welcome_email', array( $user_id ) );
}

add_action( 'send_welcome_email', 'send_welcome_email_function' );

function send_welcome_email_function( $user_id ) {
    // 获取用户信息
    $user = get_userdata( $user_id );

    // 构建邮件内容
    $subject = '欢迎加入我们的网站！';
    $message = "亲爱的 " . $user->user_login . "，nn欢迎您注册我们的网站！";

    // 发送邮件
    wp_mail( $user->user_email, $subject, $message );
}

这段代码做了以下几件事：

add_action( 'user_register', 'schedule_welcome_email' ): 当用户注册时，执行 schedule_welcome_email 函数。
schedule_welcome_email( $user_id ): 计算7天后的时间戳，然后使用 wp_schedule_single_event() 安排一个单次事件，钩子是 send_welcome_email，参数是用户 ID。
add_action( 'send_welcome_email', 'send_welcome_email_function' ): 当 send_welcome_email 钩子被触发时，执行 send_welcome_email_function 函数。
send_welcome_email_function( $user_id ): 获取用户信息，构建邮件内容，然后发送欢迎邮件。

六、调试定时任务

有时候，定时任务可能不会按预期执行。这时候，我们需要一些调试技巧。

WP-Crontrol 插件: 强烈推荐安装 WP-Crontrol 插件。它可以让你查看、编辑和删除定时任务，还可以手动运行任务，方便调试。
检查时间戳: 确保时间戳是正确的，并且是未来的时间。
检查钩子名称: 确保钩子名称拼写正确。
查看 wp_options 表: 直接查看 wp_options 表中的 cron option，看看任务是否被正确添加。
日志记录: 在钩子函数中添加日志记录，可以帮助你了解任务是否被执行，以及执行过程中是否发生错误。

七、 wp_schedule_single_event() 的局限性

wp_schedule_single_event() 虽然简单易用，但也存在一些局限性：

依赖 WordPress 的 cron 系统: WordPress 的 cron 系统并不是真正的系统 cron，而是通过访问网站时触发 wp-cron.php 来模拟的。如果网站访问量低，定时任务可能不会按时执行。
精度较低: WordPress 的 cron 精度只有分钟级别，无法精确到秒。
不适合高并发场景: 在高并发场景下，WordPress 的 cron 系统可能会出现问题。

对于需要高精度、高可靠性的定时任务，建议使用真正的系统 cron，或者使用专业的任务调度服务。

八、 wp_unschedule_event()：有始有终

既然可以安排任务，当然也可以取消任务。 WordPress 提供了 wp_unschedule_event() 函数来取消已经安排的单次事件。

function wp_unschedule_event( int $timestamp, string $hook, array $args = array(), string|object $deprecated = '' ): bool {
    $crons = _get_cron_array();

    if ( isset( $crons[ $timestamp ][ $hook ] ) ) {
        $key = md5( serialize( $args ) ); // 重新生成唯一键

        if ( isset( $crons[ $timestamp ][ $hook ][ $key ] ) ) {
            unset( $crons[ $timestamp ][ $hook ][ $key ] ); // 删除任务
            if ( empty( $crons[ $timestamp ][ $hook ] ) ) {
                unset( $crons[ $timestamp ][ $hook ] );
            }
            if ( empty( $crons[ $timestamp ] ) ) {
                unset( $crons[ $timestamp ] );
            }
            return _set_cron_array( $crons ); // 保存修改后的 cron 数组
        }
    }

    return false;
}

它的参数和 wp_schedule_single_event() 类似，需要指定时间戳、钩子和参数。 wp_unschedule_event() 会根据这些信息找到要取消的任务，然后从 cron option 中删除它。

九、总结

今天咱们深入了解了 wp_schedule_single_event() 函数的工作原理，包括它如何将定时任务添加到 wp_options 表中，以及如何使用 _get_cron_array() 和 _set_cron_array() 函数来读取和写入定时任务数据。咱们还学习了如何使用 wp_unschedule_event() 函数来取消任务。希望这些知识能帮助你更好地理解和使用 WordPress 的定时任务系统。

最后，记住，合理使用定时任务可以让你解放双手，让 WordPress 自动完成一些重复性的工作。但是，也要注意定时任务的性能问题，避免滥用，以免影响网站的性能。

好啦，今天的讲座就到这里，感谢各位的观看！如果有什么疑问，欢迎在评论区留言。我们下期再见！

发表回复 取消回复

发表回复取消回复