Cron
cron 系统可让你定义按固定间隔在后台运行的定时任务。在区块目录中添加 cron.php 文件,Blockstudio 会将这些任务注册到 WordPress Cron 并管理其生命周期。独立安装的插件会在停用时清理其任务。作为主题或其他插件一部分打包的 Composer 安装,则需要宿主执行清理,或在宿主停用、切换或移除前运行 wp bs teardown。
这是全栈区块模式的最后一环:区块可以包含 UI(index.twig)、服务器逻辑(rpc.php)、持久化数据(db.php),现在还可以包含后台处理(cron.php)。
工作原理
- 在区块目录中创建
cron.php - 它会返回一个包含命名任务的关联数组
- 每次页面加载时,Blockstudio 会检查任务是否已安排
- 尚未安排的任务会通过
wp_schedule_event()注册 - WordPress Cron 会按定义的间隔触发回调
- 独立安装的 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 的数组:
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
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 中引用:
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;
});
return [
'check_external_api' => [
'schedule' => 'every_five_minutes',
'callback' => function () { /* ... */ },
],
];
常见模式
数据维护
清理旧记录、让试用期到期、归档非活跃条目:
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 同步
按计划从第三方服务拉取数据:
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);
}
}
},
],
];
通知和摘要
定期发送报告或通知邮件:
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 仍处于加载状态时,才能使用此命令。宿主插件也可以在其主插件文件中注册清理操作:
register_deactivation_hook(__FILE__, function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
打包了该代码的主题可以在 switch_theme 上使用相同的回调。应在旧主题仍处于加载状态时注册,而不是在新主题的 after_switch_theme 钩子上注册:
add_action('switch_theme', function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
Cron::unschedule_all() 会移除所有 Blockstudio cron 事件,而不只是来自某个区块或宿主的任务。这些钩子不会移除静态预渲染状态;要彻底移除整个安装,请使用 wp bs teardown。如果不执行清理,定时事件会保留在 WordPress 中,并可能在重新安装其区块代码后恢复运行。
筛选器
以编程方式修改或禁用任务:
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触发器:
define('DISABLE_WP_CRON', true);
要检查计划事件,请使用WP-CLI:
wp cron event list | grep blockstudio