wp_clear_scheduled_hook

Advertisement

Summery Summery

Unschedules all events attached to the hook with the specified arguments.

Syntax Syntax

wp_clear_scheduled_hook( string $hook, array $args = array() )

Description Description

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 Parameters

$hook

(Required) Action hook, the execution of which will be unscheduled.

$args

(Optional) Arguments that were to be passed to the hook's callback function.

Default value: array()

Return Return

(int|false) On success an integer indicating number of events unscheduled (0 indicates no events were registered with the hook and arguments combination), false if unscheduling one or more events fail.

Source Source

File: wp-includes/cron.php

function wp_clear_scheduled_hook( $hook, $args = array() ) {
	// Backward compatibility.
	// Previously, this function took the arguments as discrete vars rather than an array like the rest of the API.
	if ( ! is_array( $args ) ) {
		_deprecated_argument( __FUNCTION__, '3.0.0', __( 'This argument has changed to an array to match the behavior of the other cron functions.' ) );
		$args = array_slice( func_get_args(), 1 ); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
	}

	/**
	 * Filter to preflight or hijack clearing a scheduled 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
	 *
	 * @param null|int|false $pre  Value to return instead. Default null to continue unscheduling 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.
	 */
	$pre = apply_filters( 'pre_clear_scheduled_hook', null, $hook, $args );
	if ( null !== $pre ) {
		return $pre;
	}

	/*
	 * This logic duplicates wp_next_scheduled().
	 * It's required due to a scenario where wp_unschedule_event() fails due to update_option() failing,
	 * and, wp_next_scheduled() returns the same schedule in an infinite loop.
	 */
	$crons = _get_cron_array();
	if ( empty( $crons ) ) {
		return 0;
	}

	$results = array();
	$key     = md5( serialize( $args ) );
	foreach ( $crons as $timestamp => $cron ) {
		if ( isset( $cron[ $hook ][ $key ] ) ) {
			$results[] = wp_unschedule_event( $timestamp, $hook, $args );
		}
	}
	if ( in_array( false, $results, true ) ) {
		return false;
	}
	return count( $results );
}

Advertisement

Changelog Changelog

Changelog
Version Description
5.1.0 Return value modified to indicate success or failure, 'pre_clear_scheduled_hook' filter added to short-circuit the function.
2.1.0 Introduced.

Advertisement

Leave a Reply