Cron
El sistema cron te permite definir tareas programadas que se ejecutan en segundo plano a intervalos periódicos. Añade un archivo cron.php al directorio de bloques y Blockstudio registra los trabajos con WordPress Cron y gestiona su ciclo de vida. Las instalaciones del plugin independiente limpian sus trabajos al desactivarse. Las instalaciones de Composer incluidas en un tema u otro plugin necesitan que el host se encargue de la limpieza o que ejecute wp bs teardown antes de desactivarse, cambiarse o eliminarse.
Esta es la última pieza del patrón de bloques full-stack: tu bloque puede tener un
UI (index.twig), lógica del servidor (rpc.php), datos persistentes (db.php) y,
ahora, procesamiento en segundo plano (cron.php).
Cómo funciona
- Creas
cron.phpen el directorio de bloques - Devuelve una matriz asociativa de trabajos con nombre
- En cada carga de página, Blockstudio comprueba si los trabajos están programados
- Los programas que faltan se registran con
wp_schedule_event() - WordPress Cron ejecuta las devoluciones de llamada en el intervalo definido
- Al desactivar el plugin independiente Blockstudio, se cancelan todos los eventos Blockstudio cron; las instalaciones incluidas en paquetes usan las rutas de limpieza que se indican a continuación
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← custom endpoints
├── db.php ← data model
├── cron.php ← background tasks
└── style.css
Definición de trabajos
Devuelve una matriz asociativa de trabajos. Cada trabajo puede ser una función de retorno directa (de forma predeterminada daily) o una matriz con schedule y 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());
},
];
Definiciones nativas de PHP
cron.php también puede devolver un objeto con métodos con atributos. Esto ofrece una
interfaz más clara y nativa de PHP, sin dejar de admitir la sintaxis de matriz 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
}
};
De forma predeterminada, los nombres de métodos se normalizan a minúsculas y snake case, así que
cleanupOldEntries() se convierte en cleanup_old_entries. Usa name: si quieres
un nombre de trabajo explícito.
Programaciones
Integradas
WordPress incluye estas programaciones de forma predeterminada:
| Programación | Intervalo |
|---|---|
hourly |
Cada hora |
twicedaily |
Cada 12 horas |
daily |
Cada 24 horas |
weekly |
Cada 7 días |
Intervalos personalizados
Registra intervalos personalizados mediante el filtro WordPress cron_schedules y luego
haz referencia a ellos en 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 () { /* ... */ },
],
];
Patrones comunes
Mantenimiento de datos
Limpia registros antiguos, caduca pruebas, archiva entradas inactivas:
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']);
}
}
},
],
];
Sincronización de API externa
Obtén datos de servicios de terceros según una programación:
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);
}
}
},
],
];
Notificaciones y resúmenes
Envía informes periódicos o correos electrónicos de notificación:
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");
},
],
];
Desactivación
Cuando Blockstudio se instala como plugin independiente, al desactivarlo se cancelan automáticamente todos los eventos Blockstudio cron.
Una instalación de Composer dentro de un tema u otro plugin no tiene su propio hook de desactivación. Al desactivar el plugin que lo aloja, cambiar de tema o eliminar el código incluido, los eventos siguen programados, a menos que el host se encargue de limpiarlos. Ejecuta el comando de desinstalación antes de hacer cualquiera de estas cosas:
wp bs teardown
Desprograma todos los eventos Blockstudio cron y elimina el estado estático de prerenderizado que pertenece a la instalación. Consulta CLI para obtener más detalles.
El comando solo está disponible mientras Blockstudio siga cargado. Como alternativa, un plugin host puede registrar la limpieza en su archivo principal:
register_deactivation_hook(__FILE__, function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
Un tema que incluya el paquete puede usar la misma devolución de llamada en switch_theme. Regístrala mientras el tema anterior siga cargado, no en el hook after_switch_theme del tema siguiente:
add_action('switch_theme', function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
Cron::unschedule_all() elimina todos los eventos Blockstudio cron, no solo los trabajos de un bloque o host. Estos hooks no eliminan el estado prerenderizado estático; usa wp bs teardown al retirar toda la instalación. Sin limpieza, los eventos periódicos permanecen en WordPress y pueden reanudarse si se vuelve a instalar el código del bloque.
Filtro
Modificar o desactivar trabajos mediante programación:
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;
});
Depuración
WordPress Cron se activa al visitar páginas, no mediante un programador a nivel del sistema.
En sitios con poco tráfico, es posible que los trabajos no se ejecuten exactamente a la hora prevista. Para una programación fiable,
configure un programador del sistema real cron que acceda a wp-cron.php:
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1
Luego desactive el activador integrado de WordPress cron en wp-config.php:
define('DISABLE_WP_CRON', true);
Para consultar los eventos programados, use WP-CLI:
wp cron event list | grep blockstudio