wp_schedule_single_event() WP 2.1.0

Устанавливает хук, который будет вызван всего один раз в указанное время. Т.е. планирует одноразовое cron событие.

Необходимость вызова хука (выполнения события) проверяется каждый раз, когда кто-либо посетил сайт.

Заметка: если при планировании нового события, в планировщике уже есть событие с таким же названием и аргументами и планируемое время нового события не превышает 10 минут от времени имеющегося события, то новое планирование будет проигнорировано.

Это поведение может измениться от начального, а первоначальное намерение кода было - не допустить планирования двух одинаковых событий в течение десяти минут друг от друга, но не препятствовать планированию одинаковых событий после десяти минут друг от друга.

События считаются одинаковыми, если совпадают: название хука и передаваемые аргументы.

Чтобы запланировать событие, повторяющееся через указанный интервал времени, используйте wp_schedule_event().

Работает на основе: _set_cron_array(), _get_cron_array(), wp_next_scheduled()

Хуки из функции:

schedule_event

Возвращает

False, если планирование событий было отменено плагином (хук 'schedule_event' возвращает false). Во всех остальных случаях ничего не возвращает - вернет NULL.

Использование

wp_schedule_single_event( $timestamp, $hook, $args );

$timestamp(число) (обязательный): Время (Timestamp) когда нужно выполнить событие. Функции сron в WP использует временную зону UTC/GMT, а не локальную (установленную в настройках), поэтому для установки времени, используйте функцию time(), на тоже возвращает время в UTC/GMT.
$hook(строка) (обязательный): Название хука, который нужно вызвать в указанное в параметре $timestamp время.
$args(массив): Параметры, которые нужно передать в функцию-обработчик хука.
По умолчанию: array()

Примеры

#1 Запланировать событие через час с текущего момента

function do_this_in_an_hour() {
	// делаем что-нибудь
}
add_action('my_new_event','do_this_in_an_hour' );

// Разместите эту строку в функцию, которая будет выполняться при каком-либо условии.
// В противном случает новое событие будет планироваться при посещении каждой страницы сайта

wp_schedule_single_event( time() + 3600, 'my_new_event' );

// time() + 3600 = 1 час с текущего момента.

#2 Как передать аргументы в функцию-обработчик

function do_this_in_an_hour( $arg1, $arg2, $arg3 ) {
	// делаем что-либо
}
add_action( 'my_new_event', 'do_this_in_an_hour', 10, 3 );

wp_schedule_single_event( time() + 3600, 'my_new_event', array( $arg1, $arg2, $arg3 ) );

Код wp schedule single event: `wp-includes/cron.php` ^{WP 4.8.1}

<?php
function wp_schedule_single_event( $timestamp, $hook, $args = array()) {
	// Make sure timestamp is a positive integer
	if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
		return false;
	}

	// Don't schedule a duplicate if there's already an identical event due within 10 minutes of it
	$next = wp_next_scheduled($hook, $args);
	if ( $next && abs( $next - $timestamp ) <= 10 * MINUTE_IN_SECONDS ) {
		return false;
	}

	$crons = _get_cron_array();
	$event = (object) array( 'hook' => $hook, 'timestamp' => $timestamp, 'schedule' => false, 'args' => $args );
	/**
	 * Filters a single event before it is scheduled.
	 *
	 * @since 3.1.0
	 *
	 * @param stdClass $event {
	 *     An object containing an event's data.
	 *
	 *     @type string       $hook      Action hook to execute when event is run.
	 *     @type int          $timestamp Unix timestamp (UTC) for when to run the event.
	 *     @type string|false $schedule  How often the event should recur. See `wp_get_schedules()`.
	 *     @type array        $args      Arguments to pass to the hook's callback function.
	 * }
	 */
	$event = apply_filters( 'schedule_event', $event );

	// A plugin disallowed this event
	if ( ! $event )
		return false;

	$key = md5(serialize($event->args));

	$crons[$event->timestamp][$event->hook][$key] = array( 'schedule' => $event->schedule, 'args' => $event->args );
	uksort( $crons, "strnatcasecmp" );
	_set_cron_array( $crons );
}

Cвязанные функции

Из метки: cron (расписание schedule)

Еще из раздела: Планировщик задач (Cron)

wp_doing_cron()