wp_unschedule_event()
Unschedule a previously scheduled event.
The $timestamp and $hook parameters are required so that the event can be identified.
Hooks from the function
Return
true|false|WP_Error
. True if event successfully unscheduled. False or WP_Error on failure.
Usage
wp_unschedule_event( $timestamp, $hook, $args, $wp_error );
- $timestamp(int) (required)
- Unix timestamp (UTC) of the event.
- $hook(string) (required)
- Action hook of the event.
- $args(array)
- 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: empty array - $wp_error(true|false)
- Whether to return a WP_Error on failure.
Default: false
Examples
#1 Remove (Cancel) the WP CRON Task
It is assumed that the function attached to the hook does not pass any data, so $args need not be specified.
$timestamp = wp_next_scheduled( 'my_schedule_hook' ); //> 1424106123 wp_unschedule_event( $timestamp, 'my_schedule_hook' );
1424106123
- is a time when task need to be executed.
See also: wp_next_scheduled().
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.
#2 Remove (Cancel) the CRON Job with the parameters
If you have specified parameters for a cron-task when registering it, you must specify those parameters in order to delete such a task, otherwise the event will not be deleted.
wp_unschedule_event( 1424106123, 'my_schedule_hook', array('id'=>654) );
Changelog
Since 2.1.0 | Introduced. |
Since 5.1.0 | Return value modified to boolean indicating success or failure, pre_unschedule_event filter added to short-circuit the function. |
Since 5.7.0 | The $wp_error parameter was added. |