Перейти до вмісту

Cron

Система cron дає змогу визначати заплановані завдання, які виконуються у фоновому режимі з регулярним інтервалом. Додайте файл cron.php до каталогу блоку, а Blockstudio зареєструє завдання за допомогою WordPress Cron і керуватиме їхнім життєвим циклом. Окремі встановлення плагіна очищують свої завдання під час деактивації. Для встановлень Composer, вбудованих у тему чи інший плагін, потрібне очищення з боку хоста або wp bs teardown перед деактивацією, перемиканням чи видаленням хоста.

Це останній елемент повностекового шаблону блока: блок може мати UI (index.twig), серверну логіку (rpc.php), постійні дані (db.php), а тепер і фонову обробку (cron.php).

Як це працює

  1. Створіть cron.php у каталозі блоку
  2. Він повертає асоціативний масив іменованих завдань
  3. Під час кожного завантаження сторінки Blockstudio перевіряє, чи заплановано завдання
  4. Відсутні розклади реєструються за допомогою wp_schedule_event()
  5. WordPress Cron запускає зворотні виклики з визначеним інтервалом
  6. Під час деактивації окремого плагіна Blockstudio усі події Blockstudio cron скасовуються; для вбудованих встановлень використовуйте наведені нижче способи очищення
Код
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php       ← custom endpoints
├── db.php        ← data model
├── cron.php      ← background tasks
└── style.css

Визначення завдань

Поверніть асоціативний масив завдань. Кожне завдання може бути прямим зворотним викликом (за замовчуванням daily) або масивом із schedule і 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());
    },
];

Визначення у стилі PHP

cron.php також може повертати об’єкт із методами та атрибутами. Це дає змогу використовувати зрозуміліший інтерфейс у стилі PHP, зберігаючи наявний синтаксис масивів.

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

За замовчуванням назви методів нормалізуються до нижнього регістру та формату snake case, тож cleanupOldEntries() стає cleanup_old_entries. Використовуйте name:, щоб задати явну назву завдання.

Розклади

Вбудовані

WordPress постачається з такими розкладами:

Розклад Інтервал
hourly Щогодини
twicedaily Кожні 12 годин
daily Кожні 24 години
weekly Кожні 7 днів

Власні інтервали

Зареєструйте власні інтервали за допомогою фільтра WordPress cron_schedules, а потім укажіть їх у 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 () { /* ... */ },
    ],
];

Типові сценарії

Обслуговування даних

Очищайте старі записи, завершуйте пробні періоди, архівуйте неактивні записи:

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

Синхронізація із зовнішнім API

Отримуйте дані сторонніх сервісів за розкладом:

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

Сповіщення та дайджести

Надсилайте періодичні звіти або листи зі сповіщеннями:

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

Деактивація

Коли Blockstudio встановлено як окремий плагін, його деактивація автоматично скасовує всі події Blockstudio cron.

Встановлення Composer усередині теми чи іншого плагіна не має власного хуку деактивації. Деактивація плагіна-хоста, перехід з його теми на іншу або видалення вбудованого коду залишає заплановані події, якщо хост не виконає очищення. Запустіть команду видалення до будь-якої з цих дій:

Командна оболонка
wp bs teardown

Вона скасовує всі події Blockstudio cron та видаляє стан статичного попереднього відтворення, яким керує інсталяція. Докладніше див. у CLI.

Команда доступна лише доки Blockstudio завантажено. Натомість плагін-хост може зареєструвати очищення у своєму головному файлі плагіна:

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

Тема, у яку вбудовано код, може використовувати той самий зворотний виклик на switch_theme. Зареєструйте його, поки завантажено стару тему, а не в хуку after_switch_theme наступної теми:

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

Cron::unschedule_all() видаляє всі події Blockstudio cron, а не лише завдання одного блоку чи хоста. Ці хуки не видаляють статичний стан попереднього рендерингу; для виведення з експлуатації всього встановлення використовуйте wp bs teardown. Без очищення повторювані події залишаються в WordPress і можуть відновитися, якщо код блоку встановити знову.

Фільтр

Змінюйте завдання програмно або вимикайте їх:

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

Налагодження

WordPress Cron запускається під час відвідування сторінок, а не системним планувальником. На сайтах із низьким трафіком завдання можуть виконуватися не точно за розкладом. Для точного часу налаштуйте справжній системний cron, який звертатиметься до wp-cron.php:

Командна оболонка
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1

Потім вимкніть вбудований тригер cron для WordPress у wp-config.php:

PHP
define('DISABLE_WP_CRON', true);

Щоб перевірити заплановані події, скористайтеся WP-CLI:

Командна оболонка
wp cron event list | grep blockstudio