WordPress Version: 6.4
/**
* WordPress Cron API
*
* @package WordPress
*/
/**
* Schedules an event to run only once.
*
* Schedules a hook which will be triggered by WordPress at the specified UTC time.
* The action will trigger when someone visits your WordPress site if the scheduled
* time has passed.
*
* Note that scheduling an event to occur within 10 minutes of an existing event
* with the same action hook will be ignored unless you pass unique `$args` values
* for each scheduled event.
*
* Use wp_next_scheduled() to prevent duplicate events.
*
* Use wp_schedule_event() to schedule a 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_single_event/
*
* @param int $timestamp Unix timestamp (UTC) for when to next run the event.
* @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_single_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;
}
$event = (object) array('hook' => $hook, 'timestamp' => $timestamp, 'schedule' => false, 'args' => $args);
/**
* Filter to override scheduling an event.
*
* Returning a non-null value will short-circuit adding the event to the
* cron array, causing the function to return the filtered value instead.
*
* Both single events and recurring events are passed through this filter;
* single events have `$event->schedule` as false, whereas recurring events
* have this set to a recurrence from wp_get_schedules(). Recurring
* events also have the integer recurrence interval set as `$event->interval`.
*
* For plugins replacing wp-cron, it is recommended you check for an
* identical event within ten minutes and apply the {@see 'schedule_event'}
* filter to check if another plugin has disallowed the event before scheduling.
*
* Return true if the event was scheduled, 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 $result The 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|false $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 Optional. The interval time in seconds for the schedule. Only present for recurring events.
* }
* @param bool $wp_error Whether to return a WP_Error on failure.
*/
$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;
}
/*
* Check for a duplicated event.
*
* Don't schedule an event if there's already an identical event
* within 10 minutes.
*
* When scheduling events within ten minutes of the current time,
* all past identical events are considered duplicates.
*
* When scheduling an event with a past timestamp (ie, before the
* current time) all events scheduled within the next ten minutes
* are considered duplicates.
*/
$crons = _get_cron_array();
$key = md5(serialize($event->args));
$duplicate = false;
if ($event->timestamp < time() + 10 * MINUTE_IN_SECONDS) {
$min_timestamp = 0;
} else {
$min_timestamp = $event->timestamp - 10 * MINUTE_IN_SECONDS;
}
if ($event->timestamp < time()) {
$max_timestamp = time() + 10 * MINUTE_IN_SECONDS;
} else {
$max_timestamp = $event->timestamp + 10 * MINUTE_IN_SECONDS;
}
foreach ($crons as $event_timestamp => $cron) {
if ($event_timestamp < $min_timestamp) {
continue;
}
if ($event_timestamp > $max_timestamp) {
break;
}
if (isset($cron[$event->hook][$key])) {
$duplicate = true;
break;
}
}
if ($duplicate) {
if ($wp_error) {
return new WP_Error('duplicate_event', __('A duplicate event already exists.'));
}
return false;
}
/**
* Modify an event before it is scheduled.
*
* @since 3.1.0
*
* @param object|false $event {
* An object containing an event's data, or boolean false to prevent the event from being scheduled.
*
* @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|false $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 Optional. The interval time in seconds for the schedule. Only present for recurring events.
* }
*/
$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;
}
$crons[$event->timestamp][$event->hook][$key] = array('schedule' => $event->schedule, 'args' => $event->args);
uksort($crons, 'strnatcasecmp');
return _set_cron_array($crons, $wp_error);
}