Cron
Le système cron vous permet de définir des tâches planifiées qui s’exécutent en arrière-plan à intervalles réguliers. Ajoutez un fichier cron.php au répertoire de votre bloc et Blockstudio enregistre les tâches auprès de WordPress Cron et gère leur cycle de vie. Les installations autonomes du plugin suppriment leurs tâches lors de la désactivation. Les installations de Composer intégrées à un thème ou à un autre plugin nécessitent un nettoyage côté hôte ou wp bs teardown avant la désactivation, le changement ou la suppression de l’hôte.
C’est la dernière pièce du modèle de bloc full-stack : votre bloc peut avoir un UI (index.twig), une logique serveur (rpc.php), des données persistantes (db.php) et désormais un traitement en arrière-plan (cron.php).
Fonctionnement
- Vous créez
cron.phpdans le répertoire de votre bloc - Il renvoie un tableau associatif de tâches nommées
- À chaque chargement de page, Blockstudio vérifie si les tâches sont planifiées
- Les planifications manquantes sont enregistrées avec
wp_schedule_event() - WordPress Cron exécute les fonctions de rappel à l’intervalle défini
- Lors de la désactivation d’un plugin Blockstudio autonome, tous les événements Blockstudio cron sont déplanifiés ; les installations intégrées utilisent les procédures de nettoyage ci-dessous
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php ← custom endpoints
├── db.php ← data model
├── cron.php ← background tasks
└── style.css
Définir des tâches
Renvoyez un tableau associatif de tâches. Chaque tâche peut être un rappel direct (daily par défaut) ou un tableau avec schedule et 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());
},
];
Définitions natives PHP
cron.php peut également renvoyer un objet avec des méthodes annotées. Cela offre une interface PHP plus épurée, tout en conservant la syntaxe de tableau existante.
<?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
}
};
Par défaut, les noms de méthode sont normalisés en minuscules avec des traits de soulignement. Ainsi, cleanupOldEntries() devient cleanup_old_entries. Utilisez name: pour définir explicitement le nom d’une tâche.
Planifications
Intégrées
WordPress fournit ces planifications prêtes à l’emploi :
| Planification | Intervalle |
|---|---|
hourly |
Toutes les heures |
twicedaily |
Toutes les 12 heures |
daily |
Toutes les 24 heures |
weekly |
Tous les 7 jours |
Intervalles personnalisés
Enregistrez des intervalles personnalisés via le filtre WordPress cron_schedules, puis référencez-les dans 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 () { /* ... */ },
],
];
Modèles courants
Maintenance des données
Nettoyez les anciens enregistrements, faites expirer les essais et archivez les entrées inactives :
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']);
}
}
},
],
];
Synchronisation externe API
Récupérez régulièrement des données depuis des services tiers :
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);
}
}
},
],
];
Notifications et récapitulatifs
Envoyez régulièrement des rapports ou des e-mails de notification :
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");
},
],
];
Désactivation
Lorsque Blockstudio est installé en tant que plugin autonome, la désactivation de ce plugin déplanifie automatiquement tous les événements Blockstudio cron.
Une installation de Composer intégrée à un thème ou à un autre plugin ne possède pas son propre hook de désactivation. La désactivation du plugin hôte, le changement de thème ou la suppression du code intégré laisse les événements planifiés, sauf si l’hôte effectue un nettoyage. Exécutez la commande de démontage avant l’une de ces opérations :
wp bs teardown
Cette commande déplanifie chaque événement Blockstudio cron et supprime l’état de pré-rendu statique appartenant à l’installation. Consultez CLI pour plus de détails.
La commande est disponible uniquement tant que Blockstudio est encore chargé. Un plugin hôte peut également enregistrer le nettoyage depuis son fichier principal :
register_deactivation_hook(__FILE__, function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
Un thème intégrant le code peut utiliser le même rappel sur switch_theme. Enregistrez-le pendant que l’ancien thème est chargé, et non sur le hook after_switch_theme du thème suivant :
add_action('switch_theme', function () {
if (class_exists(\Blockstudio\Cron::class)) {
\Blockstudio\Cron::unschedule_all();
}
});
Cron::unschedule_all() supprime tous les événements Blockstudio cron, et pas seulement les tâches d’un bloc ou d’un hôte. Ces hooks ne suppriment pas l’état du pré-rendu statique ; utilisez wp bs teardown pour retirer toute l’installation. Sans nettoyage, les événements récurrents restent dans WordPress et peuvent reprendre si le code de leur bloc est réinstallé.
Filtrer
Modifier ou désactiver des tâches par programmation :
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;
});
Débogage
WordPress Cron est déclenché par les visites de pages, et non par un planificateur au niveau du système.
Sur les sites à faible trafic, les tâches peuvent ne pas se déclencher exactement à l’heure prévue. Pour une planification fiable,
configurez une véritable tâche système cron qui appelle wp-cron.php :
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1
Désactivez ensuite le déclencheur intégré cron de WordPress dans wp-config.php :
define('DISABLE_WP_CRON', true);
Pour vérifier les événements planifiés, utilisez WP-CLI :
wp cron event list | grep blockstudio