Saltar al contenido

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

  1. Creas cron.php en el directorio de bloques
  2. Devuelve una matriz asociativa de trabajos con nombre
  3. En cada carga de página, Blockstudio comprueba si los trabajos están programados
  4. Los programas que faltan se registran con wp_schedule_event()
  5. WordPress Cron ejecuta las devoluciones de llamada en el intervalo definido
  6. 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
Código
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:

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());
    },
];

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
<?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:

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 () { /* ... */ },
    ],
];

Patrones comunes

Mantenimiento de datos

Limpia registros antiguos, caduca pruebas, archiva entradas inactivas:

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']);
                }
            }
        },
    ],
];

Sincronización de API externa

Obtén datos de servicios de terceros según una programación:

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);
                }
            }
        },
    ],
];

Notificaciones y resúmenes

Envía informes periódicos o correos electrónicos de notificación:

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");
        },
    ],
];

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:

Shell
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:

PHP
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:

PHP
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:

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;
});

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:

Shell
*/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:

PHP
define('DISABLE_WP_CRON', true);

Para consultar los eventos programados, use WP-CLI:

Shell
wp cron event list | grep blockstudio