Cron
O sistema cron permite definir tarefas agendadas que são executadas em segundo plano em intervalos recorrentes. Adicione um arquivo cron.php ao diretório do bloco, e Blockstudio registra as tarefas com WordPress Cron e gerencia seu ciclo de vida. Instalações independentes do plugin limpam suas tarefas quando ele é desativado. Instalações Composer integradas a um tema ou outro plugin precisam de uma rotina de limpeza no host ou de wp bs teardown antes que o host seja desativado, substituído ou removido.
Esta é a última parte do padrão de bloco full-stack: seu bloco pode ter um UI (index.twig), lógica no servidor (rpc.php), dados persistentes (db.php) e agora processamento em segundo plano (cron.php).
Como funciona
- Você cria
cron.phpno diretório do bloco - Ele retorna um array associativo de tarefas nomeadas
- A cada carregamento de página, Blockstudio verifica se as tarefas estão agendadas
- Os agendamentos ausentes são registrados com
wp_schedule_event() - WordPress Cron executa os callbacks no intervalo definido
- Quando um plugin Blockstudio independente é desativado, todos os eventos Blockstudio cron são desagendados; instalações integradas usam os caminhos de limpeza abaixo
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← custom endpoints
├── db.php ← data model
├── cron.php ← background tasks
└── style.css
Definição de trabalhos
Retorne um array associativo de trabalhos. Cada trabalho pode ser um callback direto (o padrão é daily) ou um array com schedule e 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());
},
];
Definições nativas de PHP
cron.php também pode retornar um objeto com métodos atribuídos. Isso oferece uma interface mais limpa e nativa de PHP, mantendo intacta a sintaxe de array existente.
<?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
}
};
Por padrão, os nomes dos métodos são normalizados para snake case em minúsculas. Assim, cleanupOldEntries() se torna cleanup_old_entries. Use name: quando quiser um nome de trabalho explícito.
Agendamentos
Integrados
WordPress oferece estes agendamentos prontos para uso:
| Agendamento | Intervalo |
|---|---|
hourly |
A cada hora |
twicedaily |
A cada 12 horas |
daily |
A cada 24 horas |
weekly |
A cada 7 dias |
Intervalos personalizados
Registre intervalos personalizados pelo filtro WordPress cron_schedules e faça referência a eles em 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 () { /* ... */ },
],
];
Padrões comuns
Manutenção de dados
Limpe registros antigos, encerre períodos de avaliação e arquive entradas inativas:
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']);
}
}
},
],
];
Sincronização externa de API
Busque dados de serviços de terceiros em intervalos programados:
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);
}
}
},
],
];
Notificações e resumos
Envie relatórios periódicos ou e-mails de notificação:
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");
},
],
];
Desativação
Quando Blockstudio é instalado como plugin independente, a desativação desse plugin desagenda automaticamente todos os eventos Blockstudio cron.
Uma instalação de Composer integrada a um tema ou outro plugin não tem um hook de desativação próprio. Desativar o plugin host, trocar o tema host ou remover o código integrado deixa os eventos agendados, a menos que o host faça a limpeza. Execute o comando de desinstalação antes de qualquer uma dessas ações:
wp bs teardown
Isso cancela o agendamento de todos os eventos Blockstudio cron e remove o estado de pré-renderização estática gerenciado pela instalação. Consulte CLI para saber mais.
O comando só fica disponível enquanto Blockstudio ainda está carregado. Como alternativa, um plugin host pode registrar a limpeza no arquivo principal do plugin:
register_deactivation_hook(__FILE__, function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
Um tema que integra o plugin pode usar o mesmo callback em switch_theme. Registre-o enquanto o tema antigo ainda está carregado, e não no hook after_switch_theme do próximo tema:
add_action('switch_theme', function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
Cron::unschedule_all() remove todos os eventos Blockstudio cron, e não apenas as tarefas de um bloco ou host. Esses hooks não removem o estado de pré-renderização estática; use wp bs teardown ao desinstalar toda a instalação. Sem a limpeza, os eventos recorrentes permanecem em WordPress e podem ser retomados se o código do bloco for instalado novamente.
Filtro
Modifique ou desative tarefas programaticamente:
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;
});
Depuração
WordPress Cron é acionado por visitas às páginas, não por um agendador no nível do sistema.
Em sites com pouco tráfego, as tarefas podem não ser executadas exatamente no horário previsto. Para garantir horários confiáveis,
configure um cron de sistema real que acesse wp-cron.php:
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1
Em seguida, desative o acionador cron integrado do WordPress em wp-config.php:
define('DISABLE_WP_CRON', true);
Para verificar os eventos agendados, use WP-CLI:
wp cron event list | grep blockstudio