wp_schedule_event( int $timestamp, string $recurrence, string $hook, array $args = array(), bool $wp_error = false ): bool|WP_Error

Description

Compatibility

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 to next run the event.

$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 scheduled. False or WP_Error on failure.

Performance profile

How much work a call to wp_schedule_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

Moderate

Reads stored settings via get_option(), cached per request but not free on a cold cache.

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

9–69

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 117.

Plugin surface

2 hooks

Third-party callbacks on 'pre_schedule_event', 'schedule_event' run inside this call, and their cost is not bounded by anything here.

Called by

11

11 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• serializeserialisationserialize()called directly
• optionoption read or writeget_option()one call below wp_schedule_event()

Further down the call graph this can also reach cache, 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 · 10 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_schedule_event() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 2

2 hooks fire while wp_schedule_event() runs, in this order:

1. 1
   apply_filters( pre_schedule_event )filterline 287 (+35 into the body)

   Filter to override scheduling an event.

2. 2
   apply_filters( schedule_event )filterline 305 (+53 into the body)

   Modify an event before it is scheduled.

Uses · 7

• __()Retrieves the translation of $text.
• wp_get_schedules()Retrieves supported event recurrence schedules.
• 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.
• _get_cron_array()Retrieves cron info array option.
• _set_cron_array()Updates the cron option with the new cron array.
• WP_Error::__construct()Initializes the error.

Used by · 11

• WP_Recovery_Mode::initialize()Initialize recovery mode for the current request.
• WP_Site_Health::maybe_create_scheduled_event()Creates a weekly cron event, if one does not already exist.
• WP_Upgrader::schedule_temp_backup_cleanup()Schedules the cleanup of the temporary backup directory.
• get_default_post_to_edit()Returns default post information to use when populating the "Write Post" form.
• wp_install()Installs the site.
• wp_reschedule_event()Reschedules a recurring event.
• wp_schedule_delete_old_privacy_export_files()Schedules a `WP_Cron` job to delete expired export files.
• wp_schedule_personal_data_cleanup_requests()Schedules a WP-Cron job to clean up personal data requests.
• wp_schedule_update_checks()Schedules core, theme, and plugin update checks.
• wp_schedule_update_network_counts()Schedules update of the network-wide counts for the current network.
• wp_schedule_update_user_counts()Schedules a recurring recalculation of the total count of users.

Source code

View on Trac ↗View on GitHub ↗

252function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array(), $wp_error = false ) {253	// Make sure timestamp is a positive integer.254	if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {255		if ( $wp_error ) {256			return new WP_Error(257				'invalid_timestamp',258				__( 'Event timestamp must be a valid Unix timestamp.' )259			);260		}261 262		return false;263	}264 265	$schedules = wp_get_schedules();266 267	if ( ! isset( $schedules[ $recurrence ] ) ) {268		if ( $wp_error ) {269			return new WP_Error(270				'invalid_schedule',271				__( 'Event schedule does not exist.' )272			);273		}274 275		return false;276	}277 278	$event = (object) array(279		'hook'      => $hook,280		'timestamp' => $timestamp,281		'schedule'  => $recurrence,282		'args'      => $args,283		'interval'  => $schedules[ $recurrence ]['interval'],284	);285 286	/** This filter is documented in wp-includes/cron.php */287	$pre = apply_filters( 'pre_schedule_event', null, $event, $wp_error );288 289	if ( null !== $pre ) {290		if ( $wp_error && false === $pre ) {291			return new WP_Error(292				'pre_schedule_event_false',293				__( 'A plugin prevented the event from being scheduled.' )294			);295		}296 297		if ( ! $wp_error && is_wp_error( $pre ) ) {298			return false;299		}300 301		return $pre;302	}303 304	/** This filter is documented in wp-includes/cron.php */305	$event = apply_filters( 'schedule_event', $event );306 307	// A plugin disallowed this event.308	if ( ! $event ) {309		if ( $wp_error ) {310			return new WP_Error(311				'schedule_event_false',312				__( 'A plugin disallowed this event.' )313			);314		}315 316		return false;317	}318 319	$key = md5( serialize( $event->args ) );320 321	$crons = _get_cron_array();322 323	$crons[ $event->timestamp ][ $event->hook ][ $key ] = array(324		'schedule' => $event->schedule,325		'args'     => $event->args,326		'interval' => $event->interval,327	);328	uksort( $crons, 'strnatcasecmp' );329 330	return _set_cron_array( $crons, $wp_error );331}

Changelog

Introduced in 2.1.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About 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.