Функция wp_clear_scheduled_hook() используется для отмены всех запланированных крон-событий, связанных с указанным хуком и переданными аргументами. Она полезна, когда нужно удалить определенные задачи из расписания Cron, чтобы они больше не выполнялись.
wp_clear_scheduled_hook( string $hook, array $args = array(), bool $wp_error = false ): int|false|WP_Error
Описание
Эта функция позволяет удалить все события, связанные с указанным хуком и, если есть, аргументами. Если были запланированы задачи с одинаковым хуком, но разными аргументами, они должны быть удалены индивидуально, указывая как хук, так и соответствующие аргументы.
- $hook — обязательный параметр, указывающий на хук, по которому запланировано событие.
- $args — необязательный массив аргументов, передаваемых в функцию при выполнении крон-задачи. Если не указаны, функция попытается удалить все задачи, связанные с хуком без аргументов.
- $wp_error — необязательный параметр, который определяет, нужно ли вернуть объект
WP_Errorпри неудаче. По умолчанию —false.
Возвращаемое значение
- int — количество удаленных событий. Если 0, значит, событие с таким хуком и аргументами не было запланировано.
- false — если не удалось удалить событие.
- WP_Error — объект ошибки, если при удалении произошел сбой (при включенном
$wp_error).
Пример 1: Удаление простой крон-задачи
Допустим, ранее была запланирована задача с хуком 'my_simple_event', которая должна была выполниться через час. Чтобы отменить эту задачу, мы можем использовать wp_clear_scheduled_hook().
// Запланируем задачу для примера
wp_schedule_single_event( time() + 3600, 'my_simple_event' );
// Отменим запланированную задачу
wp_clear_scheduled_hook( 'my_simple_event' );
Здесь мы сначала планируем событие с хуком 'my_simple_event', а затем удаляем его с помощью wp_clear_scheduled_hook().
Пример 2: Удаление крон-задачи с аргументами
Если при планировании задачи были переданы аргументы, необходимо указать их при удалении, иначе задача не будет удалена. Рассмотрим пример:
// Запланируем событие с аргументами
wp_schedule_single_event( time() + 3600, 'my_custom_event', array( 'user_id' => 123 ) );
// Удалим это событие, указав хук и аргументы
wp_clear_scheduled_hook( 'my_custom_event', array( 'user_id' => 123 ) );
Если не указать аргументы, задача не будет найдена и, следовательно, не будет удалена.
Пример 3: Удаление всех задач с одинаковым хуком, но разными аргументами
Предположим, мы запланировали несколько событий с одним и тем же хуком, но разными аргументами. Удалить их можно поочередно, передавая каждый набор аргументов.
// Запланируем несколько событий с разными аргументами
wp_schedule_single_event( time() + 3600, 'multi_event', array( 'task_id' => 1 ) );
wp_schedule_single_event( time() + 7200, 'multi_event', array( 'task_id' => 2 ) );
// Удалим каждую задачу по отдельности, указав аргументы
wp_clear_scheduled_hook( 'multi_event', array( 'task_id' => 1 ) );
wp_clear_scheduled_hook( 'multi_event', array( 'task_id' => 2 ) );
Каждая задача удаляется по своему набору аргументов.
Пример 4: Возврат ошибок при удалении крон-задачи
Иногда полезно получить дополнительную информацию о возможных ошибках при удалении задач. Для этого можно использовать параметр $wp_error.
// Попробуем удалить несуществующую задачу и получим ошибку
$result = wp_clear_scheduled_hook( 'non_existent_event', array(), true );
if ( is_wp_error( $result ) ) {
error_log( 'Ошибка: ' . $result->get_error_message() );
} else {
error_log( 'Удалено событий: ' . $result );
}
Здесь функция пытается удалить несуществующую задачу и возвращает объект ошибки, который можно использовать для записи подробной информации о сбое.
Когда использовать wp_clear_scheduled_hook()
- Отмена ненужных событий: Если вам больше не нужно, чтобы событие выполнялось по расписанию, эта функция удалит его.
- Обновление расписания: При изменении логики работы крон-задач бывает необходимо удалить старые события и запланировать новые с обновленными параметрами.
- Удаление задач с разными аргументами: Полезно, если одно и то же событие запланировано с разными наборами аргументов, и вы хотите удалить только определенные.
Заключение
Функция wp_clear_scheduled_hook() предоставляет гибкий способ отмены запланированных событий в WordPress. Она особенно полезна, когда необходимо точно управлять крон-задачами, основанными не только на хук, но и на переданных аргументах. Используя эту функцию, можно эффективно управлять расписанием задач и обеспечивать оптимальную работу планировщика в WordPress.
