Использование wp_schedule_event() в WordPress: подробное руководство с примерами

Функция wp_schedule_event() в WordPress используется для создания многоразовых крон-задач, которые выполняются с заданной регулярностью. Это может быть полезно для автоматических операций, таких как обновление данных или отправка уведомлений. В этой статье рассмотрим, как использовать данную функцию с примерами кода.

wp_schedule_event( 
    int $timestamp, 
    string $recurrence, 
    string $hook, 
    array $args = [], 
    bool $wp_error = false 
): bool|WP_Error

Параметры:

1. $timestamp (обязательно): Unix-метка времени (UTC), когда нужно выполнить событие в первый раз.
2. $recurrence (обязательно): Частота выполнения события. Возможные значения: hourly (ежечасно), twicedaily (дважды в день), daily (ежедневно) и т.д. Также можно добавить свои значения через фильтр cron_schedules.
3. $hook (обязательно): Название хука, который будет выполнен при наступлении события.
4. $args (опционально): Массив аргументов, передаваемых в функцию, привязанную к событию.
5. $wp_error (опционально): Если указано true, вернет объект WP_Error в случае неудачи.

Пример 1: Создание события при активации плагина

В этом примере создается крон-задача, которая запускается ежечасно при активации плагина.

// Регистрация крон-задачи при активации плагина
register_activation_hook( __FILE__, 'my_plugin_activation' );

// Удаление крон-задачи при деактивации
register_deactivation_hook( __FILE__, 'my_plugin_deactivation' );

// Функция активации
function my_plugin_activation() {
    // Проверка, существует ли уже задача
    if ( ! wp_next_scheduled( 'my_hourly_event' ) ) {
        // Планируем событие
        wp_schedule_event( time(), 'hourly', 'my_hourly_event' );
    }
}

// Добавляем хук, который выполнится каждый час
add_action( 'my_hourly_event', 'do_this_hourly' );

function do_this_hourly() {
    // Код, который будет выполняться каждый час
}

// Функция деактивации
function my_plugin_deactivation() {
    wp_clear_scheduled_hook( 'my_hourly_event' );
}

Описание:

• register_activation_hook() планирует событие при активации плагина.
• wp_schedule_event() устанавливает новое событие.
• wp_clear_scheduled_hook() удаляет запланированное событие при деактивации плагина.

Пример 2: Использование дополнительных аргументов

Иногда нужно передавать дополнительные данные в функцию, которая будет выполнена по расписанию.

register_activation_hook( __FILE__, 'my_plugin_activation_with_args' );

function my_plugin_activation_with_args() {
    $args = array( 'arg1', 'arg2' );
    
    if ( ! wp_next_scheduled( 'my_custom_event', $args ) ) {
        wp_schedule_event( time(), 'hourly', 'my_custom_event', $args );
    }
}

// Указываем количество передаваемых аргументов
add_action( 'my_custom_event', 'handle_custom_event', 10, 2 );

function handle_custom_event( $arg1, $arg2 ) {
    // Работа с аргументами
}

Описание:

• В wp_schedule_event() передаются дополнительные аргументы через массив $args.
• При привязке функции к событию (add_action()), обязательно укажите количество аргументов, которое будет передано.

Пример 3: Добавление пользовательского интервала

Если вам нужно выполнить событие каждые 5 минут, можно добавить собственный интервал с помощью фильтра cron_schedules.

add_filter( 'cron_schedules', 'add_five_minute_interval' );

function add_five_minute_interval( $schedules ) {
    $schedules['five_min'] = array(
        'interval' => 300, // 5 минут
        'display' => __( 'Каждые 5 минут' )
    );
    return $schedules;
}

register_activation_hook( __FILE__, 'my_plugin_activation_with_custom_interval' );

function my_plugin_activation_with_custom_interval() {
    if ( ! wp_next_scheduled( 'my_five_minute_event' ) ) {
        wp_schedule_event( time(), 'five_min', 'my_five_minute_event' );
    }
}

add_action( 'my_five_minute_event', 'handle_five_minute_event' );

function handle_five_minute_event() {
    // Код для выполнения каждые 5 минут
}

Описание:

• Используя фильтр cron_schedules, добавляется новый интервал с шагом в 5 минут.
• Далее через wp_schedule_event() планируется выполнение задачи с этим интервалом.

Пример 4: Удаление существующих событий и создание новых

Если нужно изменить интервал уже существующего события, сначала его нужно удалить, а затем добавить заново.

function update_cron_interval() {
    // Удаляем старое событие
    $timestamp = wp_next_scheduled( 'my_event' );
    if ( $timestamp ) {
        wp_unschedule_event( $timestamp, 'my_event' );
    }

    // Добавляем новое событие с обновленным интервалом
    wp_schedule_event( time(), 'twicedaily', 'my_event' );
}

Описание:

• wp_unschedule_event() удаляет событие.
• Затем создается новое событие с обновленным интервалом.

Пример 5: Использование внешних данных в крон-задаче

В этом примере каждый час обновляется курс валют с внешнего сайта.

register_activation_hook( __FILE__, 'currency_rate_activation' );
register_deactivation_hook( __FILE__, 'currency_rate_deactivation' );

add_action( 'update_currency_rate', 'fetch_currency_rate' );

function currency_rate_activation() {
    if ( ! wp_next_scheduled( 'update_currency_rate' ) ) {
        wp_schedule_event( time(), 'hourly', 'update_currency_rate' );
    }
}

function fetch_currency_rate() {
    $response = wp_remote_get( 'https://example.com/api/currency' );
    
    if ( is_array( $response ) && ! is_wp_error( $response ) ) {
        $body = wp_remote_retrieve_body( $response );
        // Обработка данных и обновление опции
        update_option( 'currency_rate', json_decode( $body ) );
    }
}

function currency_rate_deactivation() {
    wp_clear_scheduled_hook( 'update_currency_rate' );
}

Описание:

• Данные валюты обновляются с использованием wp_remote_get() каждый час и сохраняются в опции WordPress.

Заключение

Функция wp_schedule_event() — мощный инструмент для автоматизации задач в WordPress. Она позволяет легко планировать повторяющиеся действия, будь то обновление данных, рассылка писем или выполнение других задач. Важно помнить, что крон-задачи выполняются только при посещении сайта, если не отключен встроенный WP Cron.