wp_unschedule_event( int $timestamp, string $hook, array $args = array(), bool $wp_error = false ): bool|WP_Error
Unschedules a previously scheduled event.
Contents
Description
The $timestamp and $hook parameters are required so that the event can be identified.
Parameters
-
$timestampint Required -
Unix timestamp (UTC) of the event.
-
$hookstring Required -
Action hook of the event.
-
$argsarray 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:
array() -
$wp_errorbool Optional -
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.
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.
Source
File: wp-includes/cron.php.
View all references
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 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 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 preflight or hijack 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. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
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.