Функция wp_schedule_single_event() в WordPress: Руководство и Примеры

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

wp_schedule_single_event( int $timestamp, string $hook, array $args = array(), bool $wp_error = false ): bool|WP_Error

Параметры

• $timestamp (int, обязательный): Метка времени в формате UNIX (UTC), указывающая, когда нужно запустить событие.
• $hook (string, обязательный): Название хука, который будет выполнен в заданное время.
• $args (array, необязательный): Массив аргументов, передаваемых в функцию-обработчик хука. По умолчанию — пустой массив.
• $wp_error (bool, необязательный): Если установлено в true, функция вернет объект WP_Error в случае неудачи. По умолчанию — false.

Возвращаемое значение

• bool: Возвращает true, если событие успешно запланировано.
• false: Возвращает false, если произошла ошибка при планировании.
• WP_Error: Возвращает объект WP_Error, если при неудаче задан параметр $wp_error.

Описание

Функция позволяет установить одноразовое крон-событие, которое будет выполнено в указанное время. Задачи проверяются каждый раз, когда сайт посещает кто-либо из пользователей. Если время выполнения задачи наступило, она будет запущена.

Важно

Если в течение 10 минут уже запланировано событие с тем же хуком и аргументами, новое событие будет проигнорировано. Если хотите запланировать несколько событий с тем же хуком, используйте разные аргументы $args.

1. Планирование события через час

Следующий пример запланирует выполнение задачи через час с момента текущего времени.

add_action( 'my_single_event_action', 'my_event_function' );

// Запланируем выполнение хука через 1 час
function schedule_my_event() {
    if ( ! wp_next_scheduled( 'my_single_event_action' ) ) {
        wp_schedule_single_event( time() + 3600, 'my_single_event_action' );
    }
}

function my_event_function() {
    // Логика, которая выполнится через час
    error_log('Задача выполнена через час.');
}

• Функция wp_next_scheduled() проверяет, не запланировано ли уже событие с указанным хуком.
• Если событие не запланировано, создается новое крон-событие через 3600 секунд (1 час).
• Функция my_event_function() будет выполнена по прошествии этого времени.

2. Планирование события с аргументами

Вы можете передать дополнительные параметры в функцию-обработчик хука через массив $args. Эти параметры передаются непосредственно в функцию при выполнении события.

add_action( 'my_single_event_with_args', 'my_event_with_args_function', 10, 3 );

// Запланируем событие через 30 минут с аргументами
function schedule_event_with_args() {
    $args = array( 'user_id' => 101, 'email' => '[email protected]', 'count' => 5 );
    wp_schedule_single_event( time() + 1800, 'my_single_event_with_args', $args );
}

function my_event_with_args_function( $user_id, $email, $count ) {
    // Выполняем задачу с переданными параметрами
    error_log("Запланированное событие выполнено для пользователя $user_id с email $email. Количество: $count.");
}

В этом примере:

• Мы передаем массив аргументов в функцию wp_schedule_single_event().
• Эти аргументы затем передаются в обработчик хука my_event_with_args_function() при выполнении задачи.

3. Обработка ошибок при планировании события

С версии WordPress 5.7 появилась возможность возвращать объект WP_Error, если функция не смогла запланировать событие. Это полезно для обработки ошибок и предотвращения некорректной работы крон-системы.

function schedule_event_with_error_handling() {
    $result = wp_schedule_single_event( time() + 3600, 'my_single_event_action', array(), true );

    if ( is_wp_error( $result ) ) {
        error_log( 'Ошибка при планировании события: ' . $result->get_error_message() );
    } else {
        error_log( 'Событие успешно запланировано.' );
    }
}

В этом примере:

• При неудаче планирования события функция возвращает объект WP_Error, который можно использовать для логирования ошибок.

4. Запуск события по действиям пользователя

События можно запускать в ответ на действия пользователей, например, при нажатии кнопки или выполнении определенного действия на сайте. В следующем примере событие будет запланировано только после вызова определенной функции:

add_action( 'user_register_event', 'welcome_new_user_email' );

function register_user_and_schedule_event( $user_id ) {
    // Планируем отправку письма через 24 часа после регистрации пользователя
    wp_schedule_single_event( time() + DAY_IN_SECONDS, 'user_register_event', array( 'user_id' => $user_id ) );
}

function welcome_new_user_email( $user_id ) {
    // Логика отправки приветственного письма новому пользователю
    wp_mail( get_userdata( $user_id )->user_email, 'Добро пожаловать!', 'Спасибо за регистрацию на нашем сайте!' );
}

Здесь событие user_register_event будет запущено через 24 часа после регистрации нового пользователя, отправив ему приветственное письмо.

5. Отмена одноразового события

Если нужно отменить запланированное событие, можно использовать wp_unschedule_event():

$timestamp = wp_next_scheduled( 'my_single_event_action' );
if ( $timestamp ) {
    wp_unschedule_event( $timestamp, 'my_single_event_action' );
}

Это удалит ранее запланированное одноразовое событие, если оно еще не выполнено.

Заключение

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