wp_unschedule_event()
云策文档标注
概述
wp_unschedule_event() 函数用于取消之前通过 WordPress 定时任务系统安排的事件。它需要精确的时间戳和钩子名称来唯一标识事件，并可选择性地传递参数以匹配原始调度。
关键要点
- 函数用于取消已安排的定时事件，需要提供事件的时间戳（UTC Unix 时间戳）和钩子名称作为必需参数。
- 可选参数 $args 用于传递事件回调函数的参数，这些参数虽不传递给回调，但用于唯一标识事件，应与原始调度时一致。
- 可选参数 $wp_error 控制失败时是否返回 WP_Error 对象，默认返回 false。
- 成功取消返回 true，失败返回 false 或 WP_Error（取决于 $wp_error 设置）。
- 调用此函数会取消所有未来发生的事件，需确保时间戳和参数准确匹配原始调度。
- 相关函数 wp_clear_scheduled_hook() 可用于取消所有与指定钩子和参数关联的事件，简化操作。
代码示例
// 获取下一个事件的时间戳
$timestamp = wp_next_scheduled( 'my_schedule_hook' );
// 如果事件有特殊参数，需要获取这些参数
$original_args = array();
wp_unschedule_event( $timestamp, 'my_schedule_hook', $original_args );注意事项
- 取消事件前，必须知道事件的下一次运行时间戳和原始参数，否则可能无法正确取消。
- 从 WordPress 5.7.0 版本开始，添加了 $wp_error 参数；5.1.0 版本修改了返回值并添加了 'pre_unschedule_event' 过滤器。
- 使用 wp_clear_scheduled_hook() 可以避免手动调用 wp_next_scheduled()，更方便地清除所有未来事件。
原文内容
Unschedules a previously scheduled event.
Description
The $timestamp and $hook parameters are required so that the event can be identified.
Parameters
$timestampintrequired-
Unix timestamp (UTC) of the event.
$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() $wp_errorbooloptional-
Whether to return a WP_Error on failure.
Default:
false
Source
function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = false ) {
// Make sure timestamp is a positive integer.
if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
if ( $wp_error ) {
return new WP_Error(
'invalid_timestamp',
__( 'Event timestamp must be a valid Unix timestamp.' )
);
}
return false;
}
/**
* Filter to override unscheduling of events.
*
* Returning a non-null value will short-circuit the normal unscheduling
* process, causing the function to return the filtered value instead.
*
* For plugins replacing wp-cron, return true if the event was successfully
* unscheduled, false or a WP_Error if not.
*
* @since 5.1.0
* @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
*
* @param null|bool|WP_Error $pre Value to return instead. Default null to continue unscheduling the event.
* @param int $timestamp Unix timestamp (UTC) for when to run the event.
* @param string $hook Action hook, the execution of which will be unscheduled.
* @param array $args Arguments to pass to the hook's callback function.
* @param bool $wp_error Whether to return a WP_Error on failure.
*/
$pre = apply_filters( 'pre_unschedule_event', null, $timestamp, $hook, $args, $wp_error );
if ( null !== $pre ) {
if ( $wp_error && false === $pre ) {
return new WP_Error(
'pre_unschedule_event_false',
__( 'A plugin prevented the event from being unscheduled.' )
);
}
if ( ! $wp_error && is_wp_error( $pre ) ) {
return false;
}
return $pre;
}
$crons = _get_cron_array();
$key = md5( serialize( $args ) );
unset( $crons[ $timestamp ][ $hook ][ $key ] );
if ( empty( $crons[ $timestamp ][ $hook ] ) ) {
unset( $crons[ $timestamp ][ $hook ] );
}
if ( empty( $crons[ $timestamp ] ) ) {
unset( $crons[ $timestamp ] );
}
return _set_cron_array( $crons, $wp_error );
}
Hooks
- apply_filters( ‘pre_unschedule_event’, null|bool|WP_Error $pre, int $timestamp, string $hook, array $args, bool $wp_error )
-
Filter to override unscheduling of events.
Changelog
| Version | Description |
|---|---|
| 5.7.0 | The $wp_error parameter was added. |
| 5.1.0 | Return value modified to boolean indicating success or failure, ‘pre_unschedule_event’ filter added to short-circuit the function. |
| 2.1.0 | Introduced. |
Skip to note 3 content
mreall
You can also use
wp_clear_scheduled_hook(), which callswp_unschedule_event(). It will similarly clear all future events and save you from callingwp_next_scheduled()yourself.Skip to note 4 content
Codex
Example
// Get the timestamp for the next event. $timestamp = wp_next_scheduled( 'my_schedule_hook' ); // If this event was created with any special arguments, you need to get those too. $original_args = array(); wp_unschedule_event( $timestamp, 'my_schedule_hook', $original_args );