WordPress Version: 6.4
/**
* Reschedules a recurring event.
*
* Mainly for internal use, this takes the UTC timestamp of a previously run
* recurring event and reschedules it for its next run.
*
* To change upcoming scheduled events, use wp_schedule_event() to
* change the recurrence frequency.
*
* @since 2.1.0
* @since 5.1.0 Return value modified to boolean indicating success or failure,
* {@see 'pre_reschedule_event'} filter added to short-circuit the function.
* @since 5.7.0 The `$wp_error` parameter was added.
*
* @param int $timestamp Unix timestamp (UTC) for when the event was scheduled.
* @param string $recurrence How often the event should subsequently recur.
* See wp_get_schedules() for accepted values.
* @param string $hook Action hook to execute when the event is run.
* @param array $args Optional. 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.
* @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false.
* @return bool|WP_Error True if event successfully rescheduled. False or WP_Error on failure.
*/
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);
}