wp_reschedule_event( int $timestamp, string $recurrence, string $hook, array $args = array(), bool $wp_error = false ): bool|WP_Error
- Since
- 2.1.0, 5.1.0, 5.7.0
- Source
wp-includes/cron.php:367
Description
Mainly for internal use, this takes the Unix timestamp (UTC) 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.
Compatibility
- WordPress
- since 5.7.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$timestampint- Unix timestamp (UTC) for when the event was scheduled.
$recurrencestring- How often the event should subsequently recur.
See wp_get_schedules() for accepted values. $hookstring- Action hook to execute when the event is run.
$argsarrayoptional- 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.
These arguments are used to uniquely identify the scheduled event and must match those used when the event was originally scheduled. If the arguments do not match exactly, WordPress will treat the event as different, which can lead to duplicate cron events being scheduled unintentionally, excessive growth of the 'cron' option, and database performance issues.Default:array() $wp_errorbooloptional- Whether to return a WP_Error on failure. Default false.Default:
false
Return value
bool|WP_Error- True if event successfully rescheduled. False or WP_Error on failure.
Performance profile
How much work a call to wp_reschedule_event() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Trivial
- Scaling
- Constant
- Instructions
- 9–64
- Plugin surface
- 1 hook
- Called by
- 0
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 105.
Third-party callbacks on 'pre_reschedule_event' run inside this call, and their cost is not bounded by anything here.
Nothing in core calls this; the cost is only what you spend yourself.
What it touches
- hookthird-party callbacks
apply_filters()called directly
Further down the call graph this can also reach option, cache, serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 12 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_reschedule_event() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 9–11 | none |
| always | 16–18 | __() |
$interval !== 0 | 36–39 | wp_get_schedules(), apply_filters() |
$interval !== 0 && $pre !== null | 38–43 | wp_get_schedules(), apply_filters(), is_wp_error() |
$pre === null | 43–45 | wp_get_schedules(), apply_filters(), __() |
$interval === 0 | 43–50 | wp_get_schedules(), wp_get_scheduled_event(), apply_filters() |
$interval !== 0 && $pre !== null && $pre === false | 43–45 | wp_get_schedules(), apply_filters(), __(), hook() |
$interval === 0 && $pre !== null | 45–54 | wp_get_schedules(), wp_get_scheduled_event(), apply_filters(), is_wp_error() |
$interval !== 0 && $pre === null | 49–53 | wp_get_schedules(), apply_filters(), time(), wp_schedule_event() |
$interval === 0 && $pre === null | 50–56 | wp_get_schedules(), wp_get_scheduled_event(), apply_filters(), __() |
$interval === 0 && $pre !== null && $pre === false | 50–56 | wp_get_schedules(), wp_get_scheduled_event(), apply_filters(), __(), hook() |
$pre === null | 56–64 | wp_get_schedules(), wp_get_scheduled_event(), apply_filters(), time(), wp_schedule_event() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 105 | 9–64 | 15 | |
| 8.5 | 105 | 9–64 | 15 | |
| 8.4 | 105 | 9–64 | 15 | 2 fewer instructions than PHP 8.3 |
| 8.3 | 107 | 11–66 | 15 | |
| 8.2 | 107 | 11–66 | 15 | |
| 8.1 | 107 | 11–66 | 15 | |
| 7.4 | 107 | 11–66 | 15 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 1
One hook fires while wp_reschedule_event() runs, in this order:
- apply_filters( pre_reschedule_event )filterline 429 (+62 into the body)
Filter to override rescheduling of a recurring event.
Uses · 7
- __()Retrieves the translation of $text.
- wp_get_schedules()Retrieves supported event recurrence schedules.
- wp_get_scheduled_event()Retrieves a scheduled event.
- apply_filters()Calls the callback functions that have been added to a filter hook.
- is_wp_error()Checks whether the given variable is a WordPress Error.
- wp_schedule_event()Schedules a recurring event.
- WP_Error::__construct()Initializes the error.
Source code
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.Changelog
Introduced in 2.1.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
$wp_error parameter was added.from the docblockAbout this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/cron.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.