WP_SCHEDULE_SINGLE_EVENT() │ WP 2.1.0

Функция WP_SCHEDULE_SINGLE_EVENT() позволяет запланировать выполнение события один раз. Это значит, что по истечении заданного времени в формате UTC, WordPress выполнит определённое действие.

Как работает

Когда кто-то посещает ваш сайт на WordPress, если пришло время запланированного события, оно будет выполнено.

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

Чтобы избежать дублирования событий, используйте функцию wp_next_scheduled().

Если вам нужно запланироватьRecurring (повторяющееся) событие, воспользуйтесь функцией wp_schedule_event().

Используемые функции

• _set_cron_array()
• _get_cron_array()
• wp_next_scheduled()

Хуки функции

• pre_schedule_event: используется для проверки перед планировкой события.
• schedule_event: используется для планирования события.

Возврат функции

Эта функция возвращает:

• true — если событие успешно запланировано.
• false или WP_Error — если произошла ошибка.

Синтаксис использования

wp_schedule_single_event( $timestamp, $hook, $args, $wp_error );

Аргументы

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

Примеры использования

Пример 1: Запланировать событие через час

// Добавляем одноразовую задачу
add_action( 'admin_head', 'my_activation' );
add_action( 'my_new_event', 'do_this_in_an_hour' );

function my_activation() {
    if( ! wp_next_scheduled( 'my_new_event' ) ) {
        wp_schedule_single_event( time() + 3600, 'my_new_event' );
        // time() + 3600 = 1 час от текущего времени.
    }
}

function do_this_in_an_hour(){
    // Выполните что-то здесь
}

Пример 2: Как передать аргументы в функцию-обработчик

$start_time = time() + HOUR_IN_SECONDS; // через 1 час
wp_schedule_single_event( $start_time, 'my_new_event', [ $arg1, $arg2, $arg3 ] );

add_action( 'my_new_event', 'do_this_in_an_hour', 10, 3 );

function do_this_in_an_hour( $arg1, $arg2, $arg3 ){
    // Здесь можно выполнить действия с $arg1, $arg2, $arg3
}

Изменения в функции

• С версии 2.1.0 — функция была введена.
• С версии 5.1.0 — изменено значение, возвращаемое функцией, для указания успешности выполнения.
• С версии 5.7.0 — добавлен параметр $wp_error.

Связанные функции

• wp_clear_scheduled_hook(): для удаления запланированного хука.
• wp_cron(): для выполнения задач по расписанию.
• wp_delete_auto_drafts(): для удаления технологических черновиков.
• wp_get_schedules(): для получения расписаний событий.
• wp_next_scheduled(): для проверки, запланировано ли событие.
• wp_schedule_event(): для планирования повторяющихся событий.
• wp_unschedule_event(): для отмены определенного события.
• wp_unschedule_hook(): для отмены сообщений.

Теперь вы готовы к использованию WP_SCHEDULE_SINGLE_EVENT() и планированию событий на вашем сайте WordPress!