WP_UNSCHEDULE_HOOK() │ WP 4.9.0

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

Внимание: Функция может вернуть значение false или другое значение, которое будет интерпретировано как false. Для более подробной информации о приведении к логическим значениям обратитесь к документации PHP. Используйте операторы строго равенства ===, чтобы проверить, что вернула функция.

Применение функции

Функция вызывается следующим образом:

wp_unschedule_hook( $hook, $wp_error );

• $hook (string, обязательный) — имя хука, выполнение которого будет отменено.
• $wp_error (boolean) — указывает, нужно ли возвращать объект WP_Error в случае неудачи. По умолчанию: false.

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

Пример 1: Отмена всех cron-событий хука

wp_unschedule_hook( 'my_hourly_event' );

Пример 2: Отмена всех cron-событий при деактивации плагина

// При деактивации плагина отменяем ранее созданную задачу
register_deactivation_hook( __FILE__, 'my_deactivation');

// Добавляем задачу при активации плагина
register_activation_hook( __FILE__, 'my_activation' );

function my_deactivation() {
    wp_unschedule_hook( 'my_hourly_event' );
}

function my_activation() {
    // Удаляем все одинаковые cron-задачи, на всякий случай, чтобы добавить новые из "чистого листа".
    // Это может быть необходимо, если такая же задача уже была добавлена некорректно раньше 
    // (без проверки, существует ли она ��же)
    wp_unschedule_hook( 'my_hourly_event' );

    // Добавляем новую cron-задачу
    wp_schedule_event( time(), 'hourly', 'my_hourly_event');
}

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

Функция может вернуть:

• Целое число — количество отменённых событий (0 означает, что событий на хуке не было зарегистрировано).
• false или объект WP_Error, если отмена событий была неудачной.

Структура функции

Вот как выглядит основная часть кода функции:

function wp_unschedule_hook( $hook, $wp_error = false ) {
$pre = apply_filters( 'pre_unschedule_hook', null, $hook, $wp_error );

if ( null !== $pre ) {
    if ( $wp_error && false === $pre ) {
        return new WP_Error(
            'pre_unschedule_hook_false',
            __( 'Плагин предотвратил очистку хука.' )
        );
    }

    if ( ! $wp_error && is_wp_error( $pre ) ) {
        return false;
    }

    return $pre;
}

$crons = _get_cron_array();
if ( empty( $crons ) ) {
    return 0;
}

$results = array();

foreach ( $crons as $timestamp => $args ) {
    if ( ! empty( $crons[ $timestamp ][ $hook ] ) ) {
        $results[] = count( $crons[ $timestamp ][ $hook ] );
    }

    unset( $crons[ $timestamp ][ $hook ] );

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

if ( empty( $results ) ) {
    return 0;
}

$set = _set_cron_array( $crons, $wp_error );

if ( true === $set ) {
    return array_sum( $results );
}

return $set;

}

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

• С 4.9.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_schedule_single_event()
• wp_unschedule_event()

Использование функции wp_unschedule_hook() позволяет эффективно управлять задачами в WordPress и поддерживать чистоту в очереди задач.