wp_next_scheduled() │ WP 2.1.0

Returns the timestamp when the next scheduled cron job is supposed to run. Allows checking if the specified job is in the cron.

Use wp_get_scheduled_event() when you need to get the data of the cron job, not its timestamp.

Uses: wp_get_scheduled_event()
Used By: wp_schedule_single_event()
1 time — 0.001667 sec (very slow) | 50000 times — 3.12 sec (fast) | PHP 7.2.5, WP 4.9.8
Hooks from the function

Returns

Int|false. int or false: UNIX timestamp of the next specified action. If the action is not found, it will return false.

Usage

wp_next_scheduled( $hook, $args );
$hook(string) (required)
The name of the hook that will be executed after the event time occurs.
$args(array)
Arguments that should be passed to the function that is hooked. See add_action().
Default: array()

Examples

0

#1 Checking for a cron task before registering a new one

Usually events are logged when the plugin is activated. But this is not always convenient.

// make sure there is no event before registering a new cron job.
if ( ! wp_next_scheduled( 'my_hourly_event' ) ) {

	wp_schedule_event( time(), 'hourly', 'my_hourly_event' );
}

// add a function to the specified hook
add_action( 'my_hourly_event', 'do_this_hourly' );

function do_this_hourly() {
	// do something every hour
}

See wp_schedule_event() for other examples.

0

#2 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:

// This will always be false
if ( ! wp_next_scheduled( 'myevent' ) ) {
	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 );
}
0

#3 Be careful when using arguments!

WordPress doesn’t compare arguments 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 next check will not work properly and many events will be added but not only one:

if( ! wp_next_scheduled( 'action_hook', array( '123' ) ) ){

	wp_schedule_event( time(), 'daily', 'action_hook', array( 123 ) );
}

Changelog

Since 2.1.0 Introduced.

wp_next_scheduled() code WP 6.8.3

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

cron (schedule)