WP_NEXT_SCHEDULED() │ WP 2.1.0

Получение следующего времени события

Функция wp_next_scheduled() позволяет получить следующий временной штамп (timestamp) для запланированного события. Эта функция удобна для работы с задачами на cron в WordPress.

Как это работает

Функция использует wp_get_scheduled_event(), чтобы извлечь информацию о запланированном событии.

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

wp_next_scheduled( $hook, $args );

• $hook (строка, обязательный): Это "крючок" (action hook), обозначающий событие.
• $args (массив): Это массив аргументов, которые передаются в колбэк-функцию события. Эти аргументы не передаются в колбэк, но используются для уникальной идентификации события, поэтому должны совпадать с теми, которые использовались при планировании события. По умолчанию – это пустой массив.

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

• Int|false: Если событие существует, функция вернёт Unix-метку времени следующего выполнения события. В противном случае — false.

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

Пример 1: Проверка на наличие задачи перед регистрацией новой

Обычно события регистрируются при активации плагина, но это не всегда удобно.

// Убедитесь, что события не существует, прежде чем регистрировать новую задачу cron
if ( ! wp_next_scheduled( 'my_hourly_event' ) ) {
    wp_schedule_event( time(), 'hourly', 'my_hourly_event' );
}

// Добавить функцию к указанному крючку
add_action( 'my_hourly_event', 'do_this_hourly' );

function do_this_hourly() {
    // Делаем что-то каждый час
}

Смотрите wp_schedule_event(), чтобы узнать больше о других примерах.

Пример 2: Обратите внимание на параметр $args!

Если не указать параметр $args в wp_next_scheduled(), но он есть в wp_schedule_event(), то может быть запланировано множество событий, а не одно.

Плохой пример:

// Это всегда будет false
if ( ! wp_next_scheduled( 'myevent' ) ) {
    wp_schedule_event( time(), 'daily', 'myevent', array( false ) );
}

Хороший пример:

$args = array( false );
if ( ! wp_next_scheduled( 'myevent', $args ) ) {
    wp_schedule_event( time(), 'daily', 'myevent', $args );
}

Пример 3: Будьте осторожны с аргументами!

WordPress не сравнивает аргументы на 1:1, поэтому важно следить за тем, какого они типа.

Это вызвано тем, что WP генерирует хэш из них: md5( serialize( $args ) ).

Таким образом, следующая проверка может работать непра��ильно, и могут быть добавлены много событий, а не только одно:

if( ! wp_next_scheduled( 'action_hook', array( '123' ) ) ) {
    wp_schedule_event( time(), 'daily', 'action_hook', array( 123 ) );
}

Хранение кода wp_next_scheduled

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

function wp_next_scheduled( $hook, $args = array() ) {
    $next_event = wp_get_scheduled_event( $hook, $args );

    if ( ! $next_event ) {
        return false;
    }

    return $next_event->timestamp;
}

Заключение

Функция wp_next_scheduled() полезна для управления запланированными событиями в WordPress. Помните о корректной передаче аргументов, чтобы избежать дублирования событий. Используйте её для автоматизации задач и оптимизации работы вашего сайта.