wp_clear_scheduled_hook() │ WP 2.1.0

Deletes all cron jobs attached to the specified hook and having the specified parameters. Works based on wp_unschedule_event().

Differs from wp_unschedule_hook() in that it works based on wp_unschedule_event(). That is, tasks are removed not just by hook, but also by the parameters passed to the function. For example, if parameters were specified when registering the action that need to be passed to the function, then the same parameters need to be specified in this function for the specified cron job to be canceled (removed).

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

Uses: wp_unschedule_event()
Hooks from the function

Returns

Int|false|WP_Error. Returns nothing.

Usage

wp_clear_scheduled_hook( $hook, $args, $wp_error );
$hook(string) (required)
Name of the hook.
$args(array)
Arguments that are passed to the function attached to the hook.
Default: array()
$wp_error(true/false) (WP 5.7)
true - will return a WP_Error object on failure.
Default: false

Examples

0

#1 Cancel previously scheduled events

If we have added an event before, for example:

// wp_schedule_single_event( time() + 3600, 'my_new_event' );

wp_clear_scheduled_hook( 'my_new_event' );

Or if arguments was specified when adding cache:

// wp_schedule_single_event( time() + 3600, 'my_new_event', array( 'some_arg' ) );

wp_clear_scheduled_hook( 'my_new_event', array( 'some_arg' ) );

Changelog

Since 2.1.0 Introduced.
Since 5.1.0 Return value modified to indicate success or failure, pre_clear_scheduled_hook filter added to short-circuit the function.
Since 5.7.0 The $wp_error parameter was added.

wp_clear_scheduled_hook() code WP 6.9.1

wp-includes/cron.php 
function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
	/*
	 * Backward compatibility.
	 * Previously, this function took the arguments as discrete vars rather than an array like the rest of the API.
	 */
	if ( ! is_array( $args ) ) {
		_deprecated_argument(
			__FUNCTION__,
			'3.0.0',
			__( 'This argument has changed to an array to match the behavior of the other cron functions.' )
		);

		$args     = array_slice( func_get_args(), 1 ); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
		$wp_error = false;
	}

	/**
	 * Filter to override clearing a scheduled 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) or false
	 * or a WP_Error if unscheduling one or more events fails.
	 *
	 * @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 event.
	 * @param string                  $hook     Action hook, the execution of which will be unscheduled.
	 * @param array                   $args     Arguments to pass to the hook's callback function.
	 * @param bool                    $wp_error Whether to return a WP_Error on failure.
	 */
	$pre = apply_filters( 'pre_clear_scheduled_hook', null, $hook, $args, $wp_error );

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

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

		return $pre;
	}

	/*
	 * This logic duplicates wp_next_scheduled().
	 * It's required due to a scenario where wp_unschedule_event() fails due to update_option() failing,
	 * and, wp_next_scheduled() returns the same schedule in an infinite loop.
	 */
	$crons = _get_cron_array();
	if ( empty( $crons ) ) {
		return 0;
	}

	$results = array();
	$key     = md5( serialize( $args ) );

	foreach ( $crons as $timestamp => $cron ) {
		if ( isset( $cron[ $hook ][ $key ] ) ) {
			$results[] = wp_unschedule_event( $timestamp, $hook, $args, true );
		}
	}

	$errors = array_filter( $results, 'is_wp_error' );
	$error  = new WP_Error();

	if ( $errors ) {
		if ( $wp_error ) {
			array_walk( $errors, array( $error, 'merge_from' ) );

			return $error;
		}

		return false;
	}

	return count( $results );
}

cron (schedule)