Функция wp_next_scheduled() в WordPress используется для получения временной метки (timestamp) следующего запланированного события в системе Cron. Она помогает избежать повторного создания событий, которые уже были зарегистрированы, тем самым предотвращая дублирование заданий в планировщике.
wp_next_scheduled( string $hook, array $args = array() ): int|false
Параметры
- $hook (string, обязательный) — Название хука (hook) события, которое нужно проверить.
- $args (array, опциональный) — Массив аргументов, которые будут переданы в функцию-обработчик события. Эти аргументы служат для уникальной идентификации события и должны совпадать с теми, которые использовались при его создании с помощью
wp_schedule_event().
Возвращаемое значение
Функция возвращает:
- int — Метку времени (Unix timestamp) следующего запланированного события.
- false — Если событие не существует или не найдено.
Важное примечание по аргументам
При использовании параметра $args в wp_next_scheduled() и wp_schedule_event(), необходимо убедиться, что типы данных и значения аргументов точно совпадают, поскольку WordPress создает хеш на основе этих аргументов с помощью md5(serialize($args)). Например, число 123 и строка '123' будут считаться разными значениями.
Пример с ошибкой
Пример, который может привести к дублированию событий:
// Неверно, так как аргументы не указаны в wp_next_scheduled
if ( ! wp_next_scheduled( 'myevent' ) ) {
wp_schedule_event( time(), 'daily', 'myevent', array( false ) );
}
Этот код каждый раз создает новое событие, так как аргумент не передается в wp_next_scheduled, хотя используется в wp_schedule_event().
Правильный пример
Правильное использование аргументов:
$args = array( false );
if ( ! wp_next_scheduled( 'myevent', $args ) ) {
wp_schedule_event( time(), 'daily', 'myevent', $args );
}
Теперь функция проверяет наличие уже существующего события с учетом переданных аргументов, предотвращая создание лишних событий.
Пример использования wp_next_scheduled()
1. Проверка наличия события перед его созданием
Очень часто события регистрируются во время активации плагина или темы. Чтобы убедиться, что событие не дублируется, перед созданием нового события можно воспользоваться wp_next_scheduled().
if ( ! wp_next_scheduled( 'my_custom_event' ) ) {
wp_schedule_event( time(), 'hourly', 'my_custom_event' );
}
Этот код проверяет, существует ли уже событие с хуком my_custom_event. Если событие не зарегистрировано, оно создается с интервалом в один час.
2. Использование аргументов для уникальной идентификации событий
Если вы хотите создать несколько событий одного и того же типа, но с разными аргументами, можно использовать массив $args.
$args = array( 'user_id' => 42 );
if ( ! wp_next_scheduled( 'my_custom_event', $args ) ) {
wp_schedule_event( time(), 'daily', 'my_custom_event', $args );
}
Этот пример создает событие для пользователя с ID 42. При следующей проверке с помощью wp_next_scheduled(), будет учитываться, что для данного пользователя уже зарегистрировано событие, что предотвращает дублирование.
3. Обработка события
После регистрации события с помощью wp_schedule_event(), нужно добавить обработчик, который выполнит нужные действия в момент выполнения события:
add_action( 'my_custom_event', 'my_custom_event_handler', 10, 1 );
function my_custom_event_handler( $user_id ) {
// Выполнение действий для пользователя с ID $user_id
error_log( "Scheduled event triggered for user ID: " . $user_id );
}
В этом примере в журнал ошибок будет записано сообщение каждый раз, когда событие выполняется для определенного пользователя.
Заключение
Функция wp_next_scheduled() — это важный инструмент для управления запланированными событиями в WordPress. Она позволяет избежать создания дублирующих событий, помогает в точной идентификации уже существующих задач и обеспечивает корректное использование аргументов.