跳转到正文

Cron

cron 系统可让你定义按固定间隔在后台运行的定时任务。在区块目录中添加 cron.php 文件,Blockstudio 会将这些任务注册到 WordPress Cron 并管理其生命周期。独立安装的插件会在停用时清理其任务。作为主题或其他插件一部分打包的 Composer 安装,则需要宿主执行清理,或在宿主停用、切换或移除前运行 wp bs teardown。

这是全栈区块模式的最后一环:区块可以包含 UI(index.twig)、服务器逻辑(rpc.php)、持久化数据(db.php),现在还可以包含后台处理(cron.php)。

工作原理

  1. 在区块目录中创建 cron.php
  2. 它会返回一个包含命名任务的关联数组
  3. 每次页面加载时,Blockstudio 会检查任务是否已安排
  4. 尚未安排的任务会通过 wp_schedule_event() 注册
  5. WordPress Cron 会按定义的间隔触发回调
  6. 独立安装的 Blockstudio 插件停用时,所有 Blockstudio cron 事件都会被取消安排;打包安装则使用下方的清理路径
代码
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php       ← custom endpoints
├── db.php        ← data model
├── cron.php      ← background tasks
└── style.css

定义任务

返回一个任务关联数组。每个任务可以是直接回调(默认为 daily),也可以是包含 schedule 和 callback 的数组:

PHP
return [
    // Expanded format with custom schedule
    'cleanup' => [
        'schedule' => 'hourly',
        'callback' => function () {
            // runs every hour
        },
    ],

    // Shorthand: just a callback, defaults to daily
    'heartbeat' => function () {
        update_option('my_block_last_heartbeat', time());
    },
];

PHP 原生定义

cron.php 也可以返回一个包含已标注方法的对象。这样可以提供更简洁的 PHP 原生接口,同时保留现有数组语法。

PHP
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
        update_option('my_block_last_heartbeat', time());
    }

    #[Cron]
    public function cleanupOldEntries(): void {
        // defaults to daily
    }
};

默认情况下,方法名会规范化为小写蛇形命名,因此 cleanupOldEntries() 会变成 cleanup_old_entries。需要指定任务名称时,请使用 name:。

计划

内置

WordPress 开箱即提供以下计划:

计划 间隔
hourly 每小时
twicedaily 每 12 小时
daily 每 24 小时
weekly 每 7 天

自定义间隔

通过 WordPress cron_schedules 筛选器注册自定义间隔,然后在 cron.php 中引用:

PHP
add_filter('cron_schedules', function ($schedules) {
    $schedules['every_five_minutes'] = [
        'interval' => 300,
        'display'  => 'Every 5 Minutes',
    ];
    $schedules['every_fifteen_minutes'] = [
        'interval' => 900,
        'display'  => 'Every 15 Minutes',
    ];
    return $schedules;
});
PHP
return [
    'check_external_api' => [
        'schedule' => 'every_five_minutes',
        'callback' => function () { /* ... */ },
    ],
];

常见模式

数据维护

清理旧记录、让试用期到期、归档非活跃条目:

PHP
use Blockstudio\Db;

return [
    'expire_trials' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db     = Db::get('my-theme/app', 'subscribers');
            $trials = $db->list(['plan' => 'trial']);

            foreach ($trials as $trial) {
                if (strtotime($trial['created_at']) < strtotime('-14 days')) {
                    $db->update((int) $trial['id'], ['plan' => 'expired']);
                }
            }
        },
    ],
    'purge_old_logs' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db   = Db::get('my-theme/app', 'activity_log');
            $logs = $db->list();

            foreach ($logs as $log) {
                if (strtotime($log['created_at']) < strtotime('-90 days')) {
                    $db->delete((int) $log['id']);
                }
            }
        },
    ],
];

外部 API 同步

按计划从第三方服务拉取数据:

PHP
return [
    'sync_products' => [
        'schedule' => 'hourly',
        'callback' => function () {
            $response = wp_remote_get('https://api.example.com/products');

            if (is_wp_error($response)) {
                return;
            }

            $products = json_decode(wp_remote_retrieve_body($response), true);
            $db       = \Blockstudio\Db::get('my-theme/shop', 'products');

            foreach ($products as $product) {
                $existing = $db->list(['external_id' => $product['id']]);

                if (empty($existing)) {
                    $db->create($product);
                } else {
                    $db->update((int) $existing[0]['id'], $product);
                }
            }
        },
    ],
];

通知和摘要

定期发送报告或通知邮件:

PHP
use Blockstudio\Db;

return [
    'weekly_digest' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db   = Db::get('my-theme/app', 'subscribers');
            $new  = count($db->list(['status' => 'active']));
            $admin = get_option('admin_email');

            wp_mail($admin, 'Weekly Digest', "Active subscribers: $new");
        },
    ],
];

停用

当 Blockstudio 作为独立插件安装时,停用该插件会自动取消所有 Blockstudio cron 事件的安排。

如果 Composer 安装在主题或其他插件中,它本身没有停用钩子。若宿主未执行清理,停用宿主插件、切换到其他主题或移除打包代码后,已安排的事件仍会保留。在执行任何这些操作之前运行拆除命令:

命令行
wp bs teardown

它会取消所有 Blockstudio cron 事件的安排,并移除该安装所拥有的静态预渲染状态。详情请参阅 CLI详细信息。

只有在 Blockstudio 仍处于加载状态时,才能使用此命令。宿主插件也可以在其主插件文件中注册清理操作:

PHP
register_deactivation_hook(__FILE__, function () {
    if (class_exists(\Blockstudio\Cron::class)) {
        \Blockstudio\Cron::unschedule_all();
    }
});

打包了该代码的主题可以在 switch_theme 上使用相同的回调。应在旧主题仍处于加载状态时注册,而不是在新主题的 after_switch_theme 钩子上注册:

PHP
add_action('switch_theme', function () {
    if (class_exists(\Blockstudio\Cron::class)) {
        \Blockstudio\Cron::unschedule_all();
    }
});

Cron::unschedule_all() 会移除所有 Blockstudio cron 事件,而不只是来自某个区块或宿主的任务。这些钩子不会移除静态预渲染状态;要彻底移除整个安装,请使用 wp bs teardown。如果不执行清理,定时事件会保留在 WordPress 中,并可能在重新安装其区块代码后恢复运行。

筛选器

以编程方式修改或禁用任务:

PHP
add_filter('blockstudio/cron', function (array $jobs): array {
    // Disable a specific job
    unset($jobs['my-theme/app']['cleanup']);

    // Change a schedule
    if (isset($jobs['my-theme/app']['sync'])) {
        $jobs['my-theme/app']['sync']['schedule'] = 'twicedaily';
    }

    return $jobs;
});

调试

WordPress Cron由页面访问触发,而非系统级调度器。 对于流量较低的网站,任务可能不会严格按计划触发。要确保定时可靠, 请设置一个真正的系统cron,使其访问wp-cron.php:

命令行
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1

然后在wp-config.php中禁用WordPress内置的cron触发器:

PHP
define('DISABLE_WP_CRON', true);

要检查计划事件,请使用WP-CLI:

命令行
wp cron event list | grep blockstudio