wp_next_scheduled() – Function | Developer.WordPress.org

Retrieves the timestamp of the next scheduled event for the given hook.

Parameters

$hookstringrequired: Action hook of the event.
$argsarrayoptional: Array containing each separate argument to pass to the hook’s callback function.
Although not passed to a callback, these arguments are used to uniquely identify the event, so they must match those used when originally scheduling the event. If the arguments do not match exactly, the event will not be found.
Default:array()

Return

int|false The Unix timestamp (UTC) of the next time the event will occur. False if the event doesn’t exist.

Source

function wp_next_scheduled( $hook, $args = array() ) {
	$next_event = wp_get_scheduled_event( $hook, $args );

	if ( ! $next_event ) {
		return false;
	}

	/**
	 * Filters the timestamp of the next scheduled event for the given hook.
	 *
	 * @since 6.8.0
	 *
	 * @param int    $timestamp  Unix timestamp (UTC) for when to next run the event.
	 * @param object $next_event {
	 *     An object containing an event's data.
	 *
	 *     @type string $hook      Action hook of the event.
	 *     @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
	 *                             callback function.
	 *     @type int    $interval  Optional. The interval time in seconds for the schedule. Only
	 *                             present for recurring events.
	 * }
	 * @param string $hook       Action hook of the event.
	 * @param array  $args       Array containing each separate argument to pass to the hook
	 *                           callback function.
	 */
	return apply_filters( 'wp_next_scheduled', $next_event->timestamp, $next_event, $hook, $args );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_next_scheduled’, int $timestamp, object $next_event, string $hook, array $args ): Filters the timestamp of the next scheduled event for the given hook.

Uses	Description
wp_get_scheduled_event()`wp-includes/cron.php`	Retrieves a scheduled event.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Used by	Description
WP_Upgrader::schedule_temp_backup_cleanup()`wp-admin/includes/class-wp-upgrader.php`	Schedules the cleanup of the temporary backup directory.
wp_schedule_update_user_counts()`wp-includes/user.php`	Schedules a recurring recalculation of the total count of users.
wp_get_auto_update_message()`wp-admin/includes/update.php`	Determines the appropriate auto-update message to be displayed.
WP_Site_Health::maybe_create_scheduled_event()`wp-admin/includes/class-wp-site-health.php`	Creates a weekly cron event, if one does not already exist.
WP_Recovery_Mode::initialize()`wp-includes/class-wp-recovery-mode.php`	Initialize recovery mode for the current request.
wp_schedule_delete_old_privacy_export_files()`wp-includes/functions.php`	Schedules a `WP_Cron` job to delete expired export files.
populate_network()`wp-admin/includes/schema.php`	Populate network settings.
get_default_post_to_edit()`wp-admin/includes/post.php`	Returns default post information to use when populating the “Write Post” form.
wp_schedule_update_checks()`wp-includes/update.php`	Schedules core, theme, and plugin update checks.
wp_version_check()`wp-includes/update.php`	Checks WordPress version against the newest version.
_publish_post_hook()`wp-includes/post.php`	Hook to schedule pings and enclosures when a post is published.
wp_schedule_update_network_counts()`wp-includes/ms-functions.php`	Schedules update of the network-wide counts for the current network.

Show 7 more Show less

Changelog

Version	Description
2.1.0	Introduced.

User Contributed Notes

Skip to note 3 content

ub3rst4r 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 10You must log in to vote on the helpfulness of this note
Note the $args parameter! Not specifying the $args parameter in wp_next_scheduled but having $args for wp_schedule_event will cause many events to be scheduled (instead of just one).

Bad Example:
```
if ( ! wp_next_scheduled( 'myevent' ) ) { // This will always be false
	wp_schedule_event( time(), 'daily', 'myevent', array( false ) );
}
```
Good Example:
```
$args = array( false );
if ( ! wp_next_scheduled( 'myevent', $args ) ) {
	wp_schedule_event( time(), 'daily', 'myevent', $args );
}
```
Log in to add feedback
Skip to note 4 content

Kuba Mikita 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
Be careful when using arguments! WordPress doesn’t compare them 1:1 so you have to pay attention what type these are.

It’s because WP generates a hash out of them: md5( serialize( $args ) )

So when you have:
```
wp_schedule_event( time(), 'daily', 'action_hook', array( 123 ) );
```
And use a string because ie. the value was taken from the meta:
```
wp_next_scheduled( 'action_hook', array( '123' ) );
```
It will return false.
Log in to add feedback

wp_next_scheduled( string $hook, array $args = array() ): int|false

In this article

Parameters

Return

Source

Hooks

Related

Changelog

User Contributed Notes