wp_unschedule_hook()
云策文档标注
概述
wp_unschedule_hook() 函数用于取消调度所有附加到指定 Hook 的 cron 事件，适用于插件停用时清理 cron 队列。该函数支持通过过滤器 pre_unschedule_hook 进行自定义覆盖，并可根据参数返回不同状态值。
关键要点
- 功能：取消调度所有附加到指定 $hook 的 cron 事件，清理 cron 队列。
- 参数：$hook（必需，字符串，要取消调度的 Hook 名称）和 $wp_error（可选，布尔值，失败时是否返回 WP_Error，默认 false）。
- 返回值：成功时返回取消调度的事件数量（整数，0 表示无事件），失败时根据 $wp_error 返回 false 或 WP_Error。
- 过滤器：pre_unschedule_hook 过滤器允许插件覆盖默认取消调度过程，返回非 null 值将短路函数执行。
- 注意事项：返回值可能为布尔 false 或非布尔但评估为 false 的值，建议使用 === 运算符进行严格比较。
代码示例
function wp_unschedule_hook( $hook, $wp_error = false ) {
$pre = apply_filters( 'pre_unschedule_hook', null, $hook, $wp_error );
if ( null !== $pre ) {
if ( $wp_error && false === $pre ) {
return new WP_Error( 'pre_unschedule_hook_false', __( 'A plugin prevented the hook from being cleared.' ) );
}
if ( ! $wp_error && is_wp_error( $pre ) ) {
return false;
}
return $pre;
}
$crons = _get_cron_array();
if ( empty( $crons ) ) {
return 0;
}
$results = array();
foreach ( $crons as $timestamp => $args ) {
if ( ! empty( $crons[ $timestamp ][ $hook ] ) ) {
$results[] = count( $crons[ $timestamp ][ $hook ] );
}
unset( $crons[ $timestamp ][ $hook ] );
if ( empty( $crons[ $timestamp ] ) ) {
unset( $crons[ $timestamp ] );
}
}
if ( empty( $results ) ) {
return 0;
}
$set = _set_cron_array( $crons, $wp_error );
if ( true === $set ) {
return array_sum( $results );
}
return $set;
}注意事项
- 返回值处理：由于函数可能返回布尔 false 或非布尔但评估为 false 的值（如 0），测试返回值时应使用 === 运算符以避免类型混淆。
- 错误处理：通过 $wp_error 参数控制失败时返回 false 或 WP_Error 对象，便于调试和错误管理。
- 过滤器使用：pre_unschedule_hook 过滤器允许插件拦截取消调度过程，返回自定义值，需注意正确处理返回值类型以避免意外行为。
原文内容
Unschedules all events attached to the hook.
Description
Can be useful for plugins when deactivating to clean up the cron queue.
Warning: This function may return boolean false, but may also return a non-boolean value which evaluates to false. For information about casting to booleans see the PHP documentation. Use the === operator for testing the return value of this function.
Parameters
$hookstringrequired-
Action hook, the execution of which will be unscheduled.
$wp_errorbooloptional-
Whether to return a WP_Error on failure.
Default:
false
Source
function wp_unschedule_hook( $hook, $wp_error = false ) {
/**
* Filter to override clearing all events attached to the hook.
*
* 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 the number of events successfully
* unscheduled (zero if no events were registered with the hook). If unscheduling
* one or more events fails then return either a WP_Error object or false depending
* on the value of the `$wp_error` parameter.
*
* @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|int|false|WP_Error $pre Value to return instead. Default null to continue unscheduling the hook.
* @param string $hook Action hook, the execution of which will be unscheduled.
* @param bool $wp_error Whether to return a WP_Error on failure.
*/
$pre = apply_filters( 'pre_unschedule_hook', null, $hook, $wp_error );
if ( null !== $pre ) {
if ( $wp_error && false === $pre ) {
return new WP_Error(
'pre_unschedule_hook_false',
__( 'A plugin prevented the hook from being cleared.' )
);
}
if ( ! $wp_error && is_wp_error( $pre ) ) {
return false;
}
return $pre;
}
$crons = _get_cron_array();
if ( empty( $crons ) ) {
return 0;
}
$results = array();
foreach ( $crons as $timestamp => $args ) {
if ( ! empty( $crons[ $timestamp ][ $hook ] ) ) {
$results[] = count( $crons[ $timestamp ][ $hook ] );
}
unset( $crons[ $timestamp ][ $hook ] );
if ( empty( $crons[ $timestamp ] ) ) {
unset( $crons[ $timestamp ] );
}
}
/*
* If the results are empty (zero events to unschedule), no attempt
* to update the cron array is required.
*/
if ( empty( $results ) ) {
return 0;
}
$set = _set_cron_array( $crons, $wp_error );
if ( true === $set ) {
return array_sum( $results );
}
return $set;
}
Hooks
- apply_filters( ‘pre_unschedule_hook’, null|int|false|WP_Error $pre, string $hook, bool $wp_error )
-
Filter to override clearing all events attached to the hook.