Aller au contenu

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

  1. Vous créez cron.php dans le répertoire de votre bloc
  2. Il renvoie un tableau associatif de tâches nommées
  3. À chaque chargement de page, Blockstudio vérifie si les tâches sont planifiées
  4. Les planifications manquantes sont enregistrées avec wp_schedule_event()
  5. WordPress Cron exécute les fonctions de rappel à l’intervalle défini
  6. 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
Code
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 :

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

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

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

Modèles courants

Maintenance des données

Nettoyez les anciens enregistrements, faites expirer les essais et archivez les entrées inactives :

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

Synchronisation externe API

Récupérez régulièrement des données depuis des services tiers :

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

Notifications et récapitulatifs

Envoyez régulièrement des rapports ou des e-mails de notification :

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

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 :

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

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

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

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

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 :

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

PHP
define('DISABLE_WP_CRON', true);

Pour vérifier les événements planifiés, utilisez WP-CLI :

Shell
wp cron event list | grep blockstudio