WP_CLEAR_SCHEDULED_HOOK() │ WP 2.1.0

Функция wp_clear_scheduled_hook отменяет все события, которые связаны с указанным хуком и аргументами.

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

Использует

• wp_unschedule_event()

Хуки из функции

• pre_clear_scheduled_hook

Возврат

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

• int – на успехе это будет число отменённых событий (0 означает, что никаких событий не было зарегистрировано с данным хуком и комбинацией аргументов);
• false или WP_Error, если отмена одного или нескольких событий завершилась неудачей.

Использование

wp_clear_scheduled_hook( $hook, $args, $wp_error );

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

Примеры

Отмена ранее запланированных событий

Если мы ранее добавили событие, например:

// wp_schedule_single_event( time() + 3600, 'my_new_event' );
wp_clear_scheduled_hook( 'my_new_event' );

Или если были указаны аргументы при добавлении события:

// wp_schedule_single_event( time() + 3600, 'my_new_event', array( 'some_arg' ) );
wp_clear_scheduled_hook( 'my_new_event', array( 'some_arg' ) );

Добавьте свой собственный пример.

Изменения в версии

• С 2.1.0 - Функция была введена.
• С 5.1.0 - Изменено значение возврата: теперь оно указывает на успех или неудачу, добавлен фильтр pre_clear_scheduled_hook, чтобы прервать выполнение функции.
• С 5.7.0 - Добавлен параметр $wp_error.

Код функции WP_CLEAR_SCHEDULED_HOOK()

function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
    /*
     * Обратная совместимость.
     * Ранее эта функция принимала аргументы в виде отдельных переменных, а теперь - в виде массива, как и остальные функции API.
     */
    if ( ! is_array( $args ) ) {
        _deprecated_argument(
            __FUNCTION__,
            '3.0.0',
            __( 'Этот аргумент изменён на массив для совместимости с другими функциями планировщика.' )
        );

        $args     = array_slice( func_get_args(), 1 ); 
        $wp_error = false;
    }

    /**
     * Фильтр для переопределения отмены запланированного хука.
     *
     * Возвращение ненулевого значения прервет нормальный процесс отмены.
     *
     * Для плагинов, заменяющих wp-cron, верните количество успешно отменённых событий (ноль, если не было зарегистрировано событий с хуком) или false или WP_Error, если отмена одного или нескольких событий не удалась.
     *
     * @since 5.1.0
     * @since 5.7.0 Добавлен параметр $wp_error, теперь можно вернуть объект WP_Error.
     *
     * @param null|int|false|WP_Error $pre      Значение для возврата. По умолчанию null, чтобы продолжить от��ену события.
     * @param string                  $hook     Название действия, выполнение которого будет отменено.
     * @param array                   $args     Аргументы для передачи функции обратного вызова.
     * @param bool                    $wp_error Нужно ли вернуть WP_Error в случае неудачи.
     */
    $pre = apply_filters( 'pre_clear_scheduled_hook', null, $hook, $args, $wp_error );

    if ( null !== $pre ) {
        if ( $wp_error && false === $pre ) {
            return new WP_Error(
                'pre_clear_scheduled_hook_false',
                __( 'Плагин не позволил отменить хук.' )
            );
        }

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

        return $pre;
    }

    /*
     * Эта логика дублирует wp_next_scheduled().
     * Это необходимо, потому что существует сценарий, когда wp_unschedule_event() не срабатывает из-за ошибки в update_option(),
     * и wp_next_scheduled() возвращает тот же график в бесконечном цикле.
     */
    $crons = _get_cron_array();
    if ( empty( $crons ) ) {
        return 0;
    }

    $results = array();
    $key     = md5( serialize( $args ) );

    foreach ( $crons as $timestamp => $cron ) {
        if ( isset( $cron[ $hook ][ $key ] ) ) {
            $results[] = wp_unschedule_event( $timestamp, $hook, $args, true );
        }
    }

    $errors = array_filter( $results, 'is_wp_error' );
    $error  = new WP_Error();

    if ( $errors ) {
        if ( $wp_error ) {
            array_walk( $errors, array( $error, 'merge_from' ) );

            return $error;
        }

        return false;
    }

    return count( $results );
}

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

• 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()

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