wp_get_schedule()

💡 云策文档标注

概述

wp_get_schedule() 函数用于检索事件的重复计划名称，适用于 WordPress 定时任务（cron）系统。它通过事件钩子和可选参数来识别计划，返回计划名称或 false。

关键要点

函数 wp_get_schedule( $hook, $args = array() ) 接收两个参数：必需的事件钩子字符串 $hook 和可选的参数数组 $args。
返回值：成功时返回计划名称（如 'hourly'、'daily'），失败或无计划时返回 false。
该函数仅适用于重复事件（有 recurrence 计划），对于单次事件（single event）会返回 false，这可能与预期不同，需注意与 wp_next_scheduled() 的区别。
包含一个过滤器 'get_schedule'，允许在返回前修改计划名称，参数为 $schedule、$hook 和 $args。
相关函数：wp_get_scheduled_event() 用于检索事件详情，apply_filters() 用于调用过滤器钩子。

代码示例

// 示例：检索重复事件的计划名称
$schedule = wp_get_schedule( 'my_hourly_event' );
// 如果之前设置了 wp_schedule_event( current_time( 'timestamp' ), 'hourly', 'my_hourly_event' );
// $schedule 将等于 'hourly'

// 带参数的示例
$schedule = wp_get_schedule( 'my_hourly_event', array( 'some_arg' ) );
// 如果设置了 wp_schedule_single_event( current_time( 'timestamp' ), 'hourly', 'my_hourly_event', array( 'some_arg' ) );
// $schedule 将等于 'hourly'

注意事项

wp_get_schedule() 不返回时间戳，仅返回重复计划名称；对于单次事件，它总是返回 false，可能导致误用（如错误地重复调度事件）。
使用前应检查事件是否为重复事件，避免与 wp_next_scheduled() 混淆，后者返回下一次运行的时间戳。
过滤器 'get_schedule' 在 WordPress 5.1.0 版本中添加，可用于自定义计划名称逻辑。

📄 原文内容

Retrieves the name of the recurrence schedule for an event.

Description

Parameters

$hookstringrequired: Action hook to identify the event.
$argsarrayoptional: Arguments passed to the event’s callback function.

Default:array()

Return

string|false Schedule name on success, false if no schedule.

Source

function wp_get_schedule( $hook, $args = array() ) {
	$schedule = false;
	$event    = wp_get_scheduled_event( $hook, $args );

	if ( $event ) {
		$schedule = $event->schedule;
	}

	/**
	 * Filters the schedule name for a hook.
	 *
	 * @since 5.1.0
	 *
	 * @param string|false $schedule Schedule for the hook. False if not found.
	 * @param string       $hook     Action hook to execute when cron is run.
	 * @param array        $args     Arguments to pass to the hook's callback function.
	 */
	return apply_filters( 'get_schedule', $schedule, $hook, $args );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_schedule’, string|false $schedule, string $hook, array $args ): Filters the schedule name for a 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.

Changelog

Version	Description
5.1.0	‘get_schedule’ filter added.
2.1.0	Introduced.

User Contributed Notes

Skip to note 3 content

Andrei G.

10 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
I suggest that maybe the documentation here should be updated to say that the function returns false if no RECURRENCE.

I came across an issue lately with a plugin that was scheduling a single event and using wp_get_schedule() to check for the existence of a schedule.
```
if ( !wp_get_schedule( 'groups_file_access_session_delete_transients' )) {
			
			wp_schedule_single_event( time() + self::SCHEDULE, 'groups_file_access_session_delete_transients' );
		}
```
It took me a while to understand that wp_get_schedule() does not return the actual timestamp like wp_next_scheduled() , but the recurrence value, if any (hourly, daily, etc.).

As such, in the example above, the scheduling of single events was happening on every single call, causing for the cron field in the database to become gigantic.

Since wp_get_schedule() seems to not see single events (since they have no recurrence) and will always return false for single events, it is somewhat confusing.

I suspect people would expect for wp_get_schedule() to work like wp_next_scheduled() , but that’s not the case.
Log in to add feedback

Skip to note 4 content

Codex

10 years ago

Basic Examples

// If you previously added for example:
// wp_schedule_event( current_time( 'timestamp' ), 'hourly', 'my_hourly_event' );

$schedule = wp_get_schedule( 'my_hourly_event' );

// $schedule == 'hourly'

// Or this if you created something like this:
// wp_schedule_single_event( current_time( 'timestamp' ), 'hourly', 'my_hourly_event', array( 'some_arg' ) );

$schedule = wp_get_schedule( 'my_hourly_event', array( 'some_arg' ) );

// $schedule == 'hourly'

云策 WordPress 开发者社区

函数文档