wp_unschedule_event( int $timestamp, string $hook, array $args = array() )

Unschedule a previously scheduled event.


Description Description

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


Top ↑

Parameters Parameters

$timestamp

(int) (Required) Unix timestamp (UTC) of the event.

$hook

(string) (Required) Action hook of the event.

$args

(array) (Optional) 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 should be the same as those used when originally scheduling the event.

Default value: array()


Top ↑

Return Return

(bool) True if event successfully unscheduled. False for failure.


Top ↑

More Information More Information

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.


Top ↑

Source Source

File: wp-includes/cron.php

function wp_unschedule_event( $timestamp, $hook, $args = array() ) {
	// Make sure timestamp is a positive integer.
	if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
		return false;
	}

	/**
	 * Filter to preflight or hijack 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 if not.
	 *
	 * @since 5.1.0
	 *
	 * @param null|bool $pre       Value to return instead. Default null to continue unscheduling the event.
	 * @param int       $timestamp Timestamp 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.
	 */
	$pre = apply_filters( 'pre_unschedule_event', null, $timestamp, $hook, $args );
	if ( null !== $pre ) {
		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 );
}


Top ↑

Changelog Changelog

Changelog
Version Description
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.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    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.