wp_next_scheduled()
云策文档标注
概述
wp_next_scheduled() 函数用于检索指定 Hook 的下一个计划事件的 Unix 时间戳（UTC）。它通过 Hook 名称和可选参数来唯一标识事件，返回时间戳或 false（如果事件不存在）。
关键要点
- 参数 $hook（字符串，必需）：事件的动作 Hook 名称。
- 参数 $args（数组，可选）：传递给 Hook 回调函数的参数数组，用于唯一标识事件，应与原始调度事件时使用的参数一致。
- 返回值：int|false，下一个事件发生的 Unix 时间戳（UTC），事件不存在时返回 false。
- 函数内部调用 wp_get_scheduled_event() 获取事件数据，并通过 apply_filters('wp_next_scheduled', ...) 应用过滤器。
- 注意：$args 参数必须与 wp_schedule_event() 中使用的参数匹配，否则可能导致事件重复调度或识别失败。
代码示例
// 错误示例：未指定 $args 参数，可能导致事件重复调度
if ( ! wp_next_scheduled( 'myevent' ) ) {
wp_schedule_event( time(), 'daily', 'myevent', array( false ) );
}
// 正确示例：使用一致的 $args 参数
$args = array( false );
if ( ! wp_next_scheduled( 'myevent', $args ) ) {
wp_schedule_event( time(), 'daily', 'myevent', $args );
}注意事项
- 参数类型必须一致：WordPress 通过 md5(serialize($args)) 生成哈希来比较参数，因此数组中的值类型（如整数与字符串）必须匹配，否则 wp_next_scheduled() 可能返回 false。
- 示例：如果 wp_schedule_event() 使用 array(123)，而 wp_next_scheduled() 使用 array('123')，由于类型不同，函数将返回 false。
原文内容
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()
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 );
}
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.
Changelog
| Version | Description |
|---|---|
| 2.1.0 | Introduced. |
Skip to note 3 content
ub3rst4r
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 ); }Skip to note 4 content
Kuba Mikita
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.