Перейти к содержимому

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

Команда отменяет все запланированные cron-события Blockstudio и удаляет состояние статического предварительного рендеринга, принадлежащее этой установке. Подробнее см. CLI.

Команда доступна, только пока Blockstudio загружен. Вместо этого хост-плагин может зарегистрировать очистку в главном файле плагина:

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

Тема-пакет может использовать тот же callback в 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 в wp-config.php у WordPress:

PHP
define('DISABLE_WP_CRON', true);

Чтобы проверить запланированные события, используйте WP-CLI:

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