WordPress Version: 6.4
/**
* Unschedules all events attached to the hook.
*
* 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
* {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use
* the `===` operator for testing the return value of this function.
*
* @since 4.9.0
* @since 5.1.0 Return value added to indicate success or failure.
* @since 5.7.0 The `$wp_error` parameter was added.
*
* @param string $hook Action hook, the execution of which will be unscheduled.
* @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false.
* @return int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no
* events were registered on the hook), false or WP_Error if unscheduling fails.
*/
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) or false
* if unscheduling one or more events fails.
*
* @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;
}