WP_RESCHEDULE_EVENT() ─ Перенос события в WordPress

Функция wp_reschedule_event предназначена для переноса повторяющегося события на новое время. Она используется для внутренних нужд WordPress и позволяет изменить время выполнения события, которое уже было запланировано.

Когда использовать

Для изменения предстоящих запланированных событий лучше использовать функцию wp_schedule_event() для изменения частоты повторения.

Хуки функции

• pre_reschedule_event ─ Хук, который срабатывает перед переназначением события.

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

• true ─ если событие успешно перенесено.
• false или WP_Error ─ в случае неудачи.

Как использовать

Функция wp_reschedule_event принимает следующие параметры:

wp_reschedule_event( $timestamp, $recurrence, $hook, $args, $wp_error );

Параметры

• $timestamp (int, обязательный) ─ Время в формате Unix (UTC), когда событие было запланировано.
• $recurrence (string, обязательный) ─ Частота, с которой событие должно повторяться. Уточнить возможные значения можно с помощью функции wp_get_schedules().
• $hook (string, обязательный) ─ Хук действия, который нужно выполнить при запуске события.
• $args (array) ─ Массив с аргументами, которые будут переданы в функцию обратного вызова. Ключи массива игнорируются.
  • Значение по умолчанию ─ пустой массив.
• $wp_error (bool) ─ Указывает, нужно ли возвращать объект WP_Error в случае неудачи.
  • Значение по умолчанию ─ false.

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

Пример 1: Добавление Cron задачи с задержкой

Вот пример перевода события с заданным интервалом, в данном случае — один час.

$event_hook_name = 'my_currencies_update';
$interval = 'hourly';

// Убедитесь, что такая же задача не запланирована
if ( ! wp_next_scheduled( $event_hook_name ) ) {
    wp_reschedule_event( time(), $interval, $event_hook_name );
}

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

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

Код функции

Вот реализация функции wp_reschedule_event:

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

$schedules = wp_get_schedules();
$interval  = 0;

// Сначала попробуем получить интервал из расписания.
if ( isset( $schedules[ $recurrence ] ) ) {
    $interval = $schedules[ $recurrence ]['interval'];
}

// Теперь пробуем получить его из сохраненного интервала, в случае если расписание исчезнет.
if ( 0 === $interval ) {
    $scheduled_event = wp_get_scheduled_event( $hook, $args, $timestamp );

    if ( $scheduled_event && isset( $scheduled_event->interval ) ) {
        $interval = $scheduled_event->interval;
    }
}

$event = (object) array(
    'hook'      => $hook,
    'timestamp' => $timestamp,
    'schedule'  => $recurrence,
    'args'      => $args,
    'interval'  => $interval,
);

/**
 * Фильтр для переопределения переназначения повторяющегося события.
 *
 * Если вернуть ненулевое значение, процесс переназначения будет прерван,
 * и функция вернет отфильтрованное значение вместо обычного.
 *
 * @param null|bool|WP_Error $pre      Значение для возврата вместо него. Значение по умолчанию null для продолжения добавления события.
 * @param object             $event    {
 *     Объект, содержащий данные события.
 *     
 *     @type string $hook      Хук действия, которы�� нужно выполнить при запуске события.
 *     @type int    $timestamp Unix-временная метка (UTC) для следующего выполнения события.
 *     @type string $schedule  Как часто событие должно повторяться.
 *     @type array  $args      Массив, содержащий аргументы для передачи функции обратного вызова.
 *     @type int    $interval  Время интервала в секундах для расписания.
 * }
 * @param bool               $wp_error Нужно ли возвращать объект WP_Error в случае неудачи.
 */
$pre = apply_filters( 'pre_reschedule_event', null, $event, $wp_error );

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

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

    return $pre;
}

// Теперь принимаем, что что-то не так и отказались от планирования.
if ( 0 === $interval ) {
    if ( $wp_error ) {
        return new WP_Error(
            'invalid_schedule',
            __( 'Расписание события не существует.' )
        );
    }
    return false;
}

$now = time();

if ( $timestamp >= $now ) {
    $timestamp = $now + $interval;
} else {
    $timestamp = $now + ( $interval - ( ( $now - $timestamp ) % $interval ) );
}

return wp_schedule_event( $timestamp, $recurrence, $hook, $args, $wp_error );

}

Эта функция позволяет управлять всеми запланированными событиями в WordPress, делая их более гибкими и контролируемыми. Используйте её для более точного планирования повторяющихся задач в вашем проекте.