WordPress Version: 6.5
/**
* Schedules a recurring event.
*
* Schedules a hook which will be triggered by WordPress at the specified interval.
* The action will trigger when someone visits your WordPress site if the scheduled
* time has passed.
*
* Valid values for the recurrence are 'hourly', 'twicedaily', 'daily', and 'weekly'.
* These can be extended using the {@see 'cron_schedules'} filter in wp_get_schedules().
*
* Use wp_next_scheduled() to prevent duplicate events.
*
* Use wp_schedule_single_event() to schedule a non-recurring event.
*
* @since 2.1.0
* @since 5.1.0 Return value modified to boolean indicating success or failure,
* {@see 'pre_schedule_event'} filter added to short-circuit the function.
* @since 5.7.0 The `$wp_error` parameter was added.
*
* @link https://developer.wordpress.org/reference/functions/wp_schedule_event/
*
* @param int $timestamp Unix timestamp (UTC) for when to next run the event.
* @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 scheduled. False or WP_Error on failure.
*/
function wp_schedule_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();
if (!isset($schedules[$recurrence])) {
if ($wp_error) {
return new WP_Error('invalid_schedule', __('Event schedule does not exist.'));
}
return false;
}
$event = (object) array('hook' => $hook, 'timestamp' => $timestamp, 'schedule' => $recurrence, 'args' => $args, 'interval' => $schedules[$recurrence]['interval']);
/** This filter is documented in wp-includes/cron.php */
$pre = apply_filters('pre_schedule_event', null, $event, $wp_error);
if (null !== $pre) {
if ($wp_error && false === $pre) {
return new WP_Error('pre_schedule_event_false', __('A plugin prevented the event from being scheduled.'));
}
if (!$wp_error && is_wp_error($pre)) {
return false;
}
return $pre;
}
/** This filter is documented in wp-includes/cron.php */
$event = apply_filters('schedule_event', $event);
// A plugin disallowed this event.
if (!$event) {
if ($wp_error) {
return new WP_Error('schedule_event_false', __('A plugin disallowed this event.'));
}
return false;
}
$key = md5(serialize($event->args));
$crons = _get_cron_array();
$crons[$event->timestamp][$event->hook][$key] = array('schedule' => $event->schedule, 'args' => $event->args, 'interval' => $event->interval);
uksort($crons, 'strnatcasecmp');
return _set_cron_array($crons, $wp_error);
}