Vai al contenuto

Cron

Il sistema cron consente di definire attività pianificate che vengono eseguite in background a intervalli ricorrenti. Aggiungete un file cron.php alla directory del blocco e Blockstudio registra le attività con WordPress Cron e ne gestisce il ciclo di vita. Le installazioni autonome del plugin rimuovono le proprie attività alla disattivazione. Le installazioni di Composer incluse in un tema o in un altro plugin richiedono la pulizia da parte dell’host o wp bs teardown prima che l’host venga disattivato, sostituito o rimosso.

Questo è l’ultimo elemento dello schema di blocco full-stack: il blocco può avere un UI (index.twig), logica lato server (rpc.php), dati persistenti (db.php) e ora elaborazione in background (cron.php).

Come funziona

  1. Create cron.php nella directory del blocco
  2. Restituisce un array associativo di attività con nome
  3. A ogni caricamento della pagina, Blockstudio verifica se le attività sono pianificate
  4. Le pianificazioni mancanti vengono registrate con wp_schedule_event()
  5. WordPress Cron esegue i callback all’intervallo definito
  6. Alla disattivazione del plugin Blockstudio autonomo, tutti gli eventi Blockstudio cron vengono rimossi dalla pianificazione; le installazioni incluse usano i percorsi di pulizia indicati sotto
Codice
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php       ← custom endpoints
├── db.php        ← data model
├── cron.php      ← background tasks
└── style.css

Definizione dei processi

Restituite un array associativo di processi. Ogni processo può essere una callback diretta (daily per impostazione predefinita) o un array con schedule e 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());
    },
];

Definizioni native per PHP

cron.php può restituire anche un oggetto con metodi attributati. In questo modo si ottiene un’interfaccia più chiara, nativa per PHP, mantenendo intatta la sintassi array esistente.

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

Per impostazione predefinita, i nomi dei metodi vengono normalizzati in snake case minuscolo, quindi cleanupOldEntries() diventa cleanup_old_entries. Usate name: per specificare un nome esplicito per il processo.

Pianificazioni

Integrate

WordPress offre queste pianificazioni già pronte:

Pianificazione Intervallo
hourly Ogni ora
twicedaily Ogni 12 ore
daily Ogni 24 ore
weekly Ogni 7 giorni

Intervalli personalizzati

Registrate intervalli personalizzati tramite il filtro WordPress cron_schedules, quindi fatevi riferimento in 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 () { /* ... */ },
    ],
];

Schemi comuni

Manutenzione dei dati

Eliminate i record obsoleti, fate scadere le versioni di prova e archiviate le voci inattive:

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

Sincronizzazione API esterna

Recuperate dati da servizi di terze parti secondo una pianificazione:

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

Notifiche e riepiloghi

Inviate rapporti periodici o email di notifica:

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

Disattivazione

Quando Blockstudio è installato come plugin autonomo, la disattivazione del plugin rimuove automaticamente dalla pianificazione tutti gli eventi Blockstudio cron.

Un’installazione di Composer inclusa in un tema o in un altro plugin non dispone di un proprio hook di disattivazione. Disattivare il plugin host, cambiare tema o rimuovere il codice incluso lascia gli eventi pianificati, a meno che l’host non esegua la pulizia. Eseguite il comando di teardown prima di fare una di queste operazioni:

Shell
wp bs teardown

Rimuove dalla pianificazione ogni evento Blockstudio cron ed elimina lo stato di prerender statico di proprietà dell’installazione. Per i dettagli, consultate CLI.

Il comando è disponibile solo finché Blockstudio è ancora caricato. In alternativa, un plugin host può registrare la pulizia dal file principale del plugin:

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

Un tema che include il codice può usare lo stesso callback su switch_theme. Registratelo mentre il tema precedente è ancora caricato, non sull’hook after_switch_theme del tema successivo:

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

Cron::unschedule_all() rimuove tutti gli eventi Blockstudio cron, non solo le attività di un blocco o host. Questi hook non rimuovono lo stato di prerendering statico; usate wp bs teardown quando ritirate l’intera installazione. Senza pulizia, gli eventi ricorrenti restano in WordPress e possono riprendere se il codice del blocco viene installato di nuovo.

Filtro

Modifica o disabilita i processi a livello di codice:

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

Debug

WordPress Cron viene attivato dalle visite alle pagine, non da uno scheduler a livello di sistema. Nei siti con poco traffico, i processi potrebbero non essere eseguiti esattamente all’orario previsto. Per una pianificazione affidabile, configura un vero cron di sistema che richiami wp-cron.php:

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

Poi disabilita il trigger integrato cron di WordPress in wp-config.php:

PHP
define('DISABLE_WP_CRON', true);

Per controllare gli eventi pianificati, usa WP-CLI:

Shell
wp cron event list | grep blockstudio