Unschedules a previously scheduled event.
Description
The $timestamp
and $hook
parameters are required so that the event can be identified.
Parameters
$timestamp
intrequired- Unix timestamp (UTC) of the event.
$hook
stringrequired- Action hook of the event.
$args
arrayoptional- 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:
array()
$wp_error
booloptional- Whether to return a WP_Error on failure.
Default:
false
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 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.
* @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 );
}
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.
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. |
Example
You can also use
wp_clear_scheduled_hook()
, which callswp_unschedule_event()
. It will similarly clear all future events and save you from callingwp_next_scheduled()
yourself.