wp_reschedule_event() │ WP 2.1.0

Creates a new cron job that will start executing after the specified time interval.

Almost always the function adds a new cron job, even if it already exists.

The only case when the function will not add but update the data of an existing job is when the timestamp, hook name, and job parameters match, i.e., all function parameters: $timestamp, $hook, $args.

This is a wrapper for the function wp_schedule_event(), which is responsible for recalculating $timestamp and creating the next cron job.

This function differs from wp_schedule_event() in that it adds a job that will start executing after the time specified in $recurrence, while wp_schedule_event() will start executing the job immediately.

This function is used by WordPress itself in cron operations. After the next job is completed, it is removed, and a new identical job is created using this function.

Uses: wp_schedule_event()
Hooks from the function

Returns

true|false|WP_Error.

  • false or WP_Error - in case of an error when the job could not be added. The WP_Error object will only be returned when $wp_error = true.
  • true - if the job was added.

Usage

wp_reschedule_event( $timestamp, $recurrence, $hook, $args, $wp_error );
$timestamp(integer) (required)
The initial timestamp from which the hook will start working.
$recurrence(string) (required)

The name of the existing interval, indicating how often the event should repeat.

Allowed values:

  • hourly - hourly;
  • twicedaily - twice a day;
  • daily - daily.

You can add your own interval through the filter cron_schedules, which is found in the function wp_get_schedules().

$hook(string) (required)
The name of the hook to be executed.
$args(array)
The arguments to be passed to the executed hook.
Default: array()
$wp_error(true/false) (WP 5.7)
true - will return a WP_Error object on failure.
Default: false

For detailed parameter descriptions and examples, see the function description wp_schedule_event()

Examples

0

#1 Add a cron job with a delay

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.
Since 5.7.0 The $wp_error parameter was added.

wp_reschedule_event() code WP 6.8.3

wp-includes/cron.php 
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 );
}