WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

wp_next_scheduled()

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

In this article

Back to top

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 should be the same as those used when originally scheduling the event.

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 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, array $args )

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

UsesDescription
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 byDescription
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 moreShow less

Changelog

VersionDescription
2.1.0Introduced.

User Contributed Notes

  1. Skip to note 3 content
    ub3rst4r
    You must log in to vote on the helpfulness of this noteVote results for this note: 9You 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 );
}
  2. Skip to note 4 content
    Kuba Mikita
    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.

You must log in before being able to contribute a note or feedback.