WP_UNSCHEDULE_EVENT() │ WP 2.1.0

Функция wp_unschedule_event() используется для отмены ранее запланированных событий в WordPress. Она позволяет убрать событие из очереди, если оно больше не нужно.

Параметры функции

1. $timestamp (int) — Время, когда событие должно произойти. Это значение должно быть в формате Unix (UTC). Это обязательный параметр.
2. $hook (string) — Имя хука, связанного с событием, которое вы хотите отменить. Это обязательный параметр.
3. $args (array) — Массив аргументов, которые передаются функции обратного вызова. Эти аргументы помогают уникально идентифицировать событие, поэтому они должны быть такими же, как при его рег��страции. По умолчанию это пустой массив.
4. $wp_error (true|false) — Флаг, указывающий, следует ли возвращать объект WP_Error в случае ошибки. По умолчанию значение — false.

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

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

• true — если успешная отмена события,
• false или WP_Error — в случае ошибки.

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

Пример 1: Удаление задания с параметрами

Если вы указали параметры для задания при его регистрации, необходимо снова указать эти параметры, чтобы удалить задание. В противном случае событие не будет отменено.

wp_unschedule_event( 1424106123, 'my_schedule_hook', array('id' => 654) );

Пример 2: Удаление задания WP Crons

Если функция, связанная с хуком, не передает никаких данных, параметры $args можно не указывать.

$timestamp = wp_next_scheduled( 'my_schedule_hook' ); //> 1424106123
wp_unschedule_event( $timestamp, 'my_schedule_hook' );

Здесь 1424106123 — это время, когда должно было выполниться задание.

Обратите внимание: вы также можете использовать wp_clear_scheduled_hook(), которая вызывает wp_unschedule_event(). Эта функция также удаляет все будущие события и избавляет вас от необходимости самостоятельно вызывать wp_next_scheduled().

Обзор функции

Функция wp_unschedule_event определена в файле wp-includes/cron.php. Вот как она выглядит:

function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = false ) {
// Проверяем, является ли значение timestamp положительным целым числом.
if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
if ( $wp_error ) {
return new WP_Error(
'invalid_timestamp',
__( 'Timestamp события должен быть корректным Unix timestamp.' )
);
}
return false;
}

$pre = apply_filters( 'pre_unschedule_event', null, $timestamp, $hook, $args, $wp_error );

if ( null !== $pre ) {
    if ( $wp_error && false === $pre ) {
        return new WP_Error(
            'pre_unschedule_event_false',
            __( 'Плагин предотвратил отмену события.' )
        );
    }
    if ( ! $wp_error && is_wp_error( $pre ) ) {
        return false;
    }
    return $pre;
}

// Получаем массив запланированных событий.
$crons = _get_cron_array();
$key = md5( serialize( $args ) );

// Удаляем событие из массива.
unset( $crons[ $timestamp ][ $hook ][ $key ] );

if ( empty( $crons[ $timestamp ][ $hook ] ) ) {
    unset( $crons[ $timestamp ][ $hook ] );
}

if ( empty( $crons[ $timestamp ] ) ) {
    unset( $crons[ $timestamp ] );
}

return _set_cron_array( $crons, $wp_error );

}

Изменения и обновления

• С версии 2.1.0 — функция была введена.
• С версии 5.1.0 — значение возврата было изменено на boolean, что указывает на успешност�� или неудачу, добавлен фильтр pre_unschedule_event.
• С версии 5.7.0 — добавлен параметр $wp_error для возможности возврата объекта WP_Error.

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

• wp_clear_scheduled_hook() — Удаляет все запланированные события для данного хука.
• wp_cron() — Запускает запланированные задачи.
• wp_delete_auto_drafts() — Удаляет автоматические черновики.
• wp_get_schedules() — Получает доступные расписания.
• wp_next_scheduled() — Возвращает время следующего запланированного события.
• wp_schedule_event() — Регистрирует периодическое событие.
• wp_schedule_single_event() — Регистрирует одноразовое событие.
• wp_unschedule_hook() — Удаляет все задачи, связанные с хуком.