wp_unschedule_hook()WP 4.9.0

Удаляет из расписания крон абсолютно все крон задачи по указанному хуку. Тут не важно какие параметры были указаны при регистрации задачи.

Удобно использовать плагинами, когда при деактивации нужно очистить все запланированные крон задачи.

Функция похожа на wp_unschedule_event(). Разница между ними в том, что эта функция удаляет все cron события разом, нужно лишь указать название хука, к которому были прикреплены события, а wp_unschedule_event() удаляет только одну cron задачу и к тому же нужно указать параметры передаваемые функции, если они были указаны при регистрации крон-задачи.

Функция почти идентична wp_clear_scheduled_hook(), только проще, тут нужно указать только называние хука и будут удалены все задания подчистую. Тогда как в wp_clear_scheduled_hook() нужно указать название хука и аргументы передаваемые функции, если они были указаны при регистрации крон-задачи и тогда будут удалены только соответствующие крон задачи.

Подробнее об удалении крон задач: WP Cron (планировщик) в WordPress

Работает на основе: _set_cron_array()
Хуки из функции

Возвращает

int|false|WP_Error.

  • Число — при успешном выполнении, показывает количество отмененных событий.
  • 0 — указывает, что события не были зарегистрированы для хука.
  • false — означает что отмена (удаление из расписания) провалилась.

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

wp_unschedule_hook( $hook, $wp_error );
$hook(строка) (обязательный)
Название события (хука) выполнение которого нужно убрать из расписания крона.
$wp_error(true/false) (WP 5.7)
true - вернет объект WP_Error при неудаче.
По умолчанию: false

Примеры

0

#1 Отменим все крон события у хука

wp_unschedule_hook( 'my_hourly_event' );
0

#2 Отменим все крон события, при деактивации плагина

// при деактивации плагина, отменяем ранее созданную задачу
register_deactivation_hook( __FILE__, 'my_deactivation');
function my_deactivation() {
	wp_unschedule_hook( 'my_hourly_event' );
}

// добавим задачу при активации плагина
register_activation_hook( __FILE__, 'my_activation' );
function my_activation() {
	// удалим на всякий случай все такие же задачи cron, чтобы добавить новые с "чистого листа"
	// это может понадобиться, если до этого подключалась такая же задача неправильно (без проверки что она уже есть)
	wp_unschedule_hook( 'my_hourly_event' );

	// добавим новую cron задачу
	wp_schedule_event( time(), 'hourly', 'my_hourly_event');
}

Список изменений

С версии 4.9.0 Введена.
С версии 5.1.0 Return value added to indicate success or failure.
С версии 5.7.0 The $wp_error parameter was added.

Код wp_unschedule_hook() WP 6.7.1

function wp_unschedule_hook( $hook, $wp_error = false ) {
	/**
	 * Filter to override clearing all events attached to the hook.
	 *
	 * Returning a non-null value will short-circuit the normal unscheduling
	 * process, causing the function to return the filtered value instead.
	 *
	 * For plugins replacing wp-cron, return the number of events successfully
	 * unscheduled (zero if no events were registered with the hook). If unscheduling
	 * one or more events fails then return either a WP_Error object or false depending
	 * on the value of the `$wp_error` parameter.
	 *
	 * @since 5.1.0
	 * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
	 *
	 * @param null|int|false|WP_Error $pre      Value to return instead. Default null to continue unscheduling the hook.
	 * @param string                  $hook     Action hook, the execution of which will be unscheduled.
	 * @param bool                    $wp_error Whether to return a WP_Error on failure.
	 */
	$pre = apply_filters( 'pre_unschedule_hook', null, $hook, $wp_error );

	if ( null !== $pre ) {
		if ( $wp_error && false === $pre ) {
			return new WP_Error(
				'pre_unschedule_hook_false',
				__( 'A plugin prevented the hook from being cleared.' )
			);
		}

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

		return $pre;
	}

	$crons = _get_cron_array();
	if ( empty( $crons ) ) {
		return 0;
	}

	$results = array();

	foreach ( $crons as $timestamp => $args ) {
		if ( ! empty( $crons[ $timestamp ][ $hook ] ) ) {
			$results[] = count( $crons[ $timestamp ][ $hook ] );
		}

		unset( $crons[ $timestamp ][ $hook ] );

		if ( empty( $crons[ $timestamp ] ) ) {
			unset( $crons[ $timestamp ] );
		}
	}

	/*
	 * If the results are empty (zero events to unschedule), no attempt
	 * to update the cron array is required.
	 */
	if ( empty( $results ) ) {
		return 0;
	}

	$set = _set_cron_array( $crons, $wp_error );

	if ( true === $set ) {
		return array_sum( $results );
	}

	return $set;
}