wp_unschedule_event( int $timestamp, string $hook, array $args = array(), bool $wp_error = false ): bool|WP_Error

Unschedules a previously scheduled event.

Description

The $timestamp and $hook parameters are required so that the event can be identified.

Parameters

$timestampintrequired: Unix timestamp (UTC) of the event.
$hookstringrequired: Action hook of the event.
$argsarrayoptional: Array containing each separate argument to pass to the hook’s callback function.
Although not passed to a callback, these arguments are used to uniquely identify the event, so they must match those used when originally scheduling the event. If the arguments do not match exactly, the event will not be found.
Default:array()
$wp_errorbooloptional: Whether to return a WP_Error on failure.
Default:false

Return

bool|WP_Error True if event successfully unscheduled. False or WP_Error on failure.

Note that you need to know the exact time of the next occurrence when scheduled hook was set to run, and the function arguments it was supposed to have, in order to unschedule it. All future occurrences are unscheduled by calling this function.

Source

function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = false ) {
	// Make sure timestamp is a positive integer.
	if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
		if ( $wp_error ) {
			return new WP_Error(
				'invalid_timestamp',
				__( 'Event timestamp must be a valid Unix timestamp.' )
			);
		}

		return false;
	}

	/**
	 * Filter to override unscheduling of events.
	 *
	 * 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 true if the event was successfully
	 * unscheduled, false or a WP_Error if not.
	 *
	 * @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|bool|WP_Error $pre       Value to return instead. Default null to continue unscheduling the event.
	 * @param int                $timestamp Unix timestamp (UTC) for when to run 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_unschedule_event', null, $timestamp, $hook, $args, $wp_error );

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

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

		return $pre;
	}

	$crons = _get_cron_array();
	$key   = md5( serialize( $args ) );

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

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

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

	return _set_cron_array( $crons, $wp_error );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘pre_unschedule_event’, null|bool|WP_Error $pre, int $timestamp, string $hook, array $args, bool $wp_error ): Filter to override unscheduling of events.

Uses	Description
_get_cron_array()`wp-includes/cron.php`	Retrieves cron info array option.
_set_cron_array()`wp-includes/cron.php`	Updates the cron option with the new cron array.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
is_wp_error()`wp-includes/load.php`	Checks whether the given variable is a WordPress Error.
WP_Error::__construct()`wp-includes/class-wp-error.php`	Initializes the error.

Show 4 more Show less

Used by	Description
wp_clear_scheduled_hook()`wp-includes/cron.php`	Unschedules all events attached to the hook with the specified arguments.

Changelog

Version	Description
5.7.0	The `$wp_error` parameter was added.
5.1.0	Return value modified to boolean indicating success or failure, 'pre_unschedule_event' filter added to short-circuit the function.
2.1.0	Introduced.

User Contributed Notes

Skip to note 3 content

mreall 4 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

You can also use wp_clear_scheduled_hook(), which calls wp_unschedule_event(). It will similarly clear all future events and save you from calling wp_next_scheduled() yourself.

Log in to add feedback

Codex 10 years ago

Example

// Get the timestamp for the next event.
$timestamp = wp_next_scheduled( 'my_schedule_hook' );

// If this event was created with any special arguments, you need to get those too.
$original_args = array();

wp_unschedule_event( $timestamp, 'my_schedule_hook', $original_args );

You must log in before being able to contribute a note or feedback.

wp_unschedule_event( int $timestamp, string $hook, array $args = array(), bool $wp_error = false ): bool|WP_Error

In this article