wp_schedule_single_event( int $timestamp, 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:48
Description
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.
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 to next run the event.
$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_single_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
- Heavy
- Scaling
- Scales with input
- Instructions
- 8–96
- Plugin surface
- 2 hooks
- Called by
- 15
Reads stored settings via get_option(), cached per request but not free on a cold cache.
The body loops, so the work grows with what you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 150.
Third-party callbacks on 'pre_schedule_event', 'schedule_event' run inside this call, and their cost is not bounded by anything here.
15 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()called directly - serializeserialisation
serialize()called directly - optionoption read or write
get_option()one call below wp_schedule_single_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 · 15 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_schedule_single_event() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 8–10 | none |
| always | 15–17 | __() |
$pre !== null && $pre !== false | 27 | apply_filters() |
$pre !== null | 28–31 | apply_filters(), is_wp_error() |
$pre !== null && $pre === false | 33 | apply_filters(), __(), hook() |
$pre === null | 58–71 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time() |
$pre === null | 60–73 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time(), time() |
$pre === null | 64–77 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time(), apply_filters() |
$pre === null | 65–78 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time(), __() |
$pre === null | 66–79 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time(), time(), apply_filters() |
$pre === null | 67–80 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time(), time(), __() |
$pre === null | 71–84 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time(), apply_filters(), __() |
3 further outcomes, up to 96 instructions
$pre === null | 73–86 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time(), time(), apply_filters(), __() |
$pre === null | 81–94 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time(), apply_filters(), uksort(), _set_cron_array() |
$pre === null | 83–96 | apply_filters(), _get_cron_array(), serialize(), md5(), time(), time(), time(), apply_filters(), uksort(), _set_cron_array() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 150 | 8–96 | 19 | |
| 8.5 | 150 | 8–96 | 19 | |
| 8.4 | 150 | 8–96 | 19 | 2 fewer instructions than PHP 8.3 |
| 8.3 | 152 | 10–98 | 19 | |
| 8.2 | 152 | 10–98 | 19 | |
| 8.1 | 152 | 10–98 | 19 | |
| 7.4 | 152 | 10–98 | 19 |
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 · 2
2 hooks fire while wp_schedule_single_event() runs, in this order:
- apply_filters( pre_schedule_event )filterline 100 (+52 into the body)
Filter to override scheduling an event.
- apply_filters( schedule_event )filterline 188 (+140 into the body)
Modify an event before it is scheduled.
Uses · 6
- __()Retrieves the translation of $text.
- 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 · 15
- File_Upload_Upgrader::__construct()Construct the upgrader for a form.
- WP_Automatic_Updater::after_core_update()Checks whether to send an email and avoid processing future updates after attempting a core update.
- _future_post_hook()Hook used to schedule publication for a post marked for the future.
- _publish_post_hook()Hook to schedule pings and enclosures when a post is published.
- _wp_batch_split_terms()Splits a batch of shared taxonomy terms.
- _wp_batch_update_comment_type()Updates the comment type for a batch of comments.
- _wp_check_for_scheduled_split_terms()In order to avoid the _wp_batch_split_terms() job being accidentally removed, checks that it's still scheduled while we haven't finished splitting terms.
- _wp_check_for_scheduled_update_comment_type()In order to avoid the _wp_batch_update_comment_type() job being accidentally removed, check that it's still scheduled while we haven't finished updating comment types.
- check_and_publish_future_post()Publishes future post and make sure post ID has future post status.
- upgrade_210()Execute changes made in WordPress 2.1.
- upgrade_430()Executes changes made in WordPress 4.3.0.
- upgrade_550()Executes changes made in WordPress 5.5.0.
Show all 15
- wp_delete_all_temp_backups()Schedules the removal of all contents in the temporary backup directory.
- wp_import_handle_upload()Handles importer uploading and adds attachment.
- wp_version_check()Checks WordPress version against the newest version.
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.