wp_unschedule_hook() │ WP 4.9.0

Deletes all cron tasks from the schedule for the specified hook. It does not matter what parameters were specified when registering the task.

Convenient to use with plugins when deactivating needs to clear all scheduled cron tasks.

The function is similar to wp_unschedule_event(). The difference between them is that this function removes all cron events at once; you only need to specify the name of the hook to which the events were attached, while wp_unschedule_event() removes only one cron task and also requires specifying the parameters passed to the function if they were specified when registering the cron task.

The function is almost identical to wp_clear_scheduled_hook(), only simpler; here you only need to specify the name of the hook, and all tasks will be completely removed. In contrast, in wp_clear_scheduled_hook(), you need to specify the name of the hook and the arguments passed to the function if they were specified when registering the cron task, and then only the corresponding cron tasks will be removed.

More about deleting cron tasks: WP Cron (scheduler) in WordPress

Uses: _set_cron_array()
Hooks from the function

Returns

Int|false|WP_Error.

  • int — on successful execution, shows the number of canceled events.
  • 0 — indicates that no events were registered for the hook.
  • false — means that the cancellation (removal from the schedule) failed.

Usage

wp_unschedule_hook( $hook, $wp_error );
$hook(string) (required)
The name of the event (hook) whose execution needs to be removed from the cron schedule.
$wp_error(true/false) (WP 5.7)
true - will return a WP_Error object on failure.
Default: false

Examples

0

#1 Remove (Cancel) all Cron events of the CRON hook 

wp_unschedule_hook( 'my_hourly_event' );
0

#2 Cancel all cron events when the plugin is deactivated 

// when deactivating the plugin, cancel the previously created task
register_deactivation_hook( __FILE__, 'my_deactivation');

// add a task when the plugin is activated
register_activation_hook( __FILE__, 'my_activation' );

function my_deactivation() {
	wp_unschedule_hook( 'my_hourly_event' );
}

function my_activation() {

	// Delete all the same cron tasks, just in case, to add new ones from a "clean slate".
	// This may be necessary if the same task was added incorrectly before 
	// (without checking if it already exists)
	wp_unschedule_hook( 'my_hourly_event' );

	// add a new cron task
	wp_schedule_event( time(), 'hourly', 'my_hourly_event');
}

Changelog

Since 4.9.0 Introduced.
Since 5.1.0 Return value added to indicate success or failure.
Since 5.7.0 The $wp_error parameter was added.

wp_unschedule_hook() code WP 6.9.1

wp-includes/cron.php 
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;
}

cron (schedule)