云策 WordPress 开发者社区

函数文档

wp_get_scheduled_event()

查看官方原文 ↗
💡 云策文档标注

概述

wp_get_scheduled_event() 函数用于检索 WordPress 中已调度的事件对象。它可以根据指定的钩子、参数和时间戳来获取事件详情，若无时间戳则返回下一个预定事件。

关键要点

  • 函数参数包括必需的 $hook（事件的动作钩子）、可选的 $args（传递给回调函数的参数数组，用于唯一标识事件）和可选的 $timestamp（Unix 时间戳，UTC）。
  • 返回值是一个事件对象，包含 hook、timestamp、schedule、args 和可选的 interval 属性；若事件不存在则返回 false。
  • 函数内部使用 _get_cron_array() 获取 cron 数组，并通过 md5(serialize($args)) 生成唯一键来定位事件。
  • 提供 pre_get_scheduled_event 过滤器，允许在检索事件前进行自定义处理，返回非 null 值可短路正常流程。
  • 注意事项：$args 参数在查找带参数的事件时不是可选的，如果未提供且事件有参数，函数可能返回 null 或 false。

代码示例

// 示例：检查并移除旧事件
if ( false !== wp_get_scheduled_event( 'old_hook' ) ) {
    wp_clear_scheduled_hook( 'old_hook' );
}
📄 原文内容

Retrieves a scheduled event.

Description

Retrieves the full event object for a given event, if no timestamp is specified the next scheduled event is returned.

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()

$timestampint|nulloptional
Unix timestamp (UTC) of the event. If not specified, the next scheduled event is returned.

Default:null

Return

object|false The event object. False if the event does not exist.

  • hook string
    Action hook to execute when the event is run.
  • timestamp int
    Unix timestamp (UTC) for when to next run the event.
  • schedule string|false
    How often the event should subsequently recur.
  • args array
    Array containing each separate argument to pass to the hook’s callback function.
  • interval int
    Optional. The interval time in seconds for the schedule. Only present for recurring events.

Source

function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) {
	/**
	 * Filter to override retrieving a scheduled event.
	 *
	 * Returning a non-null value will short-circuit the normal process,
	 * returning the filtered value instead.
	 *
	 * Return false if the event does not exist, otherwise an event object
	 * should be returned.
	 *
	 * @since 5.1.0
	 *
	 * @param null|false|object $pre  Value to return instead. Default null to continue retrieving the event.
	 * @param string            $hook Action hook of the event.
	 * @param array             $args 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.
	 * @param int|null  $timestamp Unix timestamp (UTC) of the event. Null to retrieve next scheduled event.
	 */
	$pre = apply_filters( 'pre_get_scheduled_event', null, $hook, $args, $timestamp );

	if ( null !== $pre ) {
		return $pre;
	}

	if ( null !== $timestamp && ! is_numeric( $timestamp ) ) {
		return false;
	}

	$crons = _get_cron_array();
	if ( empty( $crons ) ) {
		return false;
	}

	$key = md5( serialize( $args ) );

	if ( ! $timestamp ) {
		// Get next event.
		$next = false;
		foreach ( $crons as $timestamp => $cron ) {
			if ( isset( $cron[ $hook ][ $key ] ) ) {
				$next = $timestamp;
				break;
			}
		}

		if ( ! $next ) {
			return false;
		}

		$timestamp = $next;
	} elseif ( ! isset( $crons[ $timestamp ][ $hook ][ $key ] ) ) {
		return false;
	}

	$event = (object) array(
		'hook'      => $hook,
		'timestamp' => $timestamp,
		'schedule'  => $crons[ $timestamp ][ $hook ][ $key ]['schedule'],
		'args'      => $args,
	);

	if ( isset( $crons[ $timestamp ][ $hook ][ $key ]['interval'] ) ) {
		$event->interval = $crons[ $timestamp ][ $hook ][ $key ]['interval'];
	}

	return $event;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘pre_get_scheduled_event’, null|false|object $pre, string $hook, array $args, int|null $timestamp )

Filter to override retrieving a scheduled event.

Uses Description
_get_cron_array()wp-includes/cron.php

Retrieves cron info array option.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
Used by Description
wp_reschedule_event()wp-includes/cron.php

Reschedules a recurring event.
wp_next_scheduled()wp-includes/cron.php

Retrieves the timestamp of the next scheduled event for the given hook.
wp_get_schedule()wp-includes/cron.php

Retrieves the name of the recurrence schedule for an event.

Changelog

Version Description
5.1.0 Introduced.

User Contributed Notes