Функция wp_unschedule_event() позволяет удалить конкретное крон-событие, запланированное ранее через wp_schedule_event(). Для этого необходимо указать точное время выполнения задачи, имя хука и аргументы, если они использовались при регистрации.
wp_unschedule_event( int $timestamp, string $hook, array $args = array(), bool $wp_error = false ): bool|WP_Error
Параметры
- $timestamp (int, обязательный): Время события в формате UNIX (UTC), когда задача должна быть выполнена.
- $hook (string, обязательный): Имя хука, с которым было связано событие.
- $args (array, необязательный): Массив аргументов, переданных при регистрации задачи. По умолчанию — пустой массив.
- $wp_error (bool, необязательный): Если установлено в
true, функция вернет объектWP_Errorпри неудаче. По умолчаниюfalse.
Возвращаемое значение
- bool: Возвращает
true, если событие успешно удалено. - false: Возвращает
false, если произошла ошибка. - WP_Error: Возвращает объект
WP_Error, если опция$wp_errorустановлена вtrueи произошла ошибка.
Применение
Функция полезна для удаления конкретных крон-задач. Например, если вы хотите отменить выполнение задачи, запланированной на определенное время, то вам нужно знать точный таймстамп и аргументы, если они использовались при регистрации.
1. Удаление задачи без параметров
Если крон-задача была зарегистрирована без дополнительных аргументов, ее можно легко удалить, зная только точное время ее выполнения и имя хука.
// Получаем время следующего выполнения события
$timestamp = wp_next_scheduled('my_custom_cron_task');
// Удаляем событие, если оно запланировано
if ($timestamp) {
wp_unschedule_event($timestamp, 'my_custom_cron_task');
}
2. Удаление задачи с параметрами
Если при регистрации крон-задачи использовались аргументы, их обязательно нужно указать при удалении события. Например:
// Получаем таймстамп следующего события с указанными аргументами
$timestamp = wp_next_scheduled('my_custom_cron_task', array('id' => 123));
// Удаляем событие с параметром 'id' => 123
if ($timestamp) {
wp_unschedule_event($timestamp, 'my_custom_cron_task', array('id' => 123));
}
3. Обработка ошибок при удалении задачи
С версии WordPress 5.7 добавлена возможность возврата объекта WP_Error при неудаче. Это полезно, если вам нужно обрабатывать ошибки при удалении событий:
// Получаем таймстамп следующего события
$timestamp = wp_next_scheduled('my_custom_cron_task');
// Пытаемся удалить событие и проверяем результат
$result = wp_unschedule_event($timestamp, 'my_custom_cron_task', array(), true);
if (is_wp_error($result)) {
// Обработка ошибки
echo 'Ошибка при удалении события: ' . $result->get_error_message();
} else {
echo 'Событие успешно удалено';
}
4. Автоматическая отмена крон-задачи при деактивации плагина
Пример удаления крон-задачи при деактивации плагина:
register_deactivation_hook(__FILE__, 'my_plugin_deactivation');
function my_plugin_deactivation() {
// Получаем время следующего выполнения задачи
$timestamp = wp_next_scheduled('my_daily_task');
// Если задача запланирована, удаляем ее
if ($timestamp) {
wp_unschedule_event($timestamp, 'my_daily_task');
}
}
Этот код показывает, как при деактивации плагина удалить запланированную крон-задачу, чтобы предотвратить ее выполнение после отключения плагина.
5. Удаление повторяющихся событий
Если вам нужно удалить все будущие повторяющиеся события, связанные с определенным хуком и параметрами, вы можете использовать следующий подход:
// Удаляем все будущие события, запланированные с хуком 'my_hourly_task'
while ($timestamp = wp_next_scheduled('my_hourly_task')) {
wp_unschedule_event($timestamp, 'my_hourly_task');
}
Этот пример демонстрирует, как удалить все будущие запланированные события для указанного хука, пока таких событий больше не останется.
Заключение
Функция wp_unschedule_event() позволяет точно управлять крон-задачами в WordPress. Она требует указания времени события и имени хука, а также аргументов (если использовались) для успешного удаления запланированной задачи.