Unix timestamp (UTC) for when the event was scheduled.
$recurrence(string) (required)
How often the event should subsequently recur. See wp_get_schedules() for accepted values.
$hook(string) (required)
Action hook to execute when the event is run.
$args(array)
Array containing arguments to pass to the hook's callback function. Each value in the array is passed to the callback as an individual parameter. The array keys are ignored. Default: empty array
$wp_error(true|false)
Whether to return a WP_Error on failure. Default: false
A cron job added in this way will start after a specified interval - one hour from the current moment.
$event_hook_name = 'my_currencies_update';
$interval = 'hourly';
// make sure there is no same cron task
if ( ! wp_next_scheduled( $event_hook_name ) ) {
wp_reschedule_event( time(), $interval, $event_hook_name );
}
Changelog
Since 2.1.0
Introduced.
Since 5.1.0
Return value modified to boolean indicating success or failure, pre_reschedule_event filter added to short-circuit the function.
function wp_reschedule_event( $timestamp, $recurrence, $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;
}
$schedules = wp_get_schedules();
$interval = 0;
// First we try to get the interval from the schedule.
if ( isset( $schedules[ $recurrence ] ) ) {
$interval = $schedules[ $recurrence ]['interval'];
}
// Now we try to get it from the saved interval in case the schedule disappears.
if ( 0 === $interval ) {
$scheduled_event = wp_get_scheduled_event( $hook, $args, $timestamp );
if ( $scheduled_event && isset( $scheduled_event->interval ) ) {
$interval = $scheduled_event->interval;
}
}
$event = (object) array(
'hook' => $hook,
'timestamp' => $timestamp,
'schedule' => $recurrence,
'args' => $args,
'interval' => $interval,
);
/**
* Filter to override rescheduling of a recurring event.
*
* Returning a non-null value will short-circuit the normal rescheduling
* process, causing the function to return the filtered value instead.
*
* For plugins replacing wp-cron, return true if the event was successfully
* rescheduled, 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 adding the event.
* @param object $event {
* An object containing an event's data.
*
* @type string $hook Action hook to execute when the event is run.
* @type int $timestamp Unix timestamp (UTC) for when to next run the event.
* @type string $schedule How often the event should subsequently recur.
* @type array $args Array containing each separate argument to pass to the hook's callback function.
* @type int $interval The interval time in seconds for the schedule.
* }
* @param bool $wp_error Whether to return a WP_Error on failure.
*/
$pre = apply_filters( 'pre_reschedule_event', null, $event, $wp_error );
if ( null !== $pre ) {
if ( $wp_error && false === $pre ) {
return new WP_Error(
'pre_reschedule_event_false',
__( 'A plugin prevented the event from being rescheduled.' )
);
}
if ( ! $wp_error && is_wp_error( $pre ) ) {
return false;
}
return $pre;
}
// Now we assume something is wrong and fail to schedule.
if ( 0 === $interval ) {
if ( $wp_error ) {
return new WP_Error(
'invalid_schedule',
__( 'Event schedule does not exist.' )
);
}
return false;
}
$now = time();
if ( $timestamp >= $now ) {
$timestamp = $now + $interval;
} else {
$timestamp = $now + ( $interval - ( ( $now - $timestamp ) % $interval ) );
}
return wp_schedule_event( $timestamp, $recurrence, $hook, $args, $wp_error );
}