WordPress.org

Languages: English • 日本語 (Add your language)

Description

Schedules a hook which will be executed once by the WordPress actions core at a time which you specify. The action will fire off when someone visits your WordPress site, if the schedule time has passed.

Usage

 <?php wp_schedule_single_event( $timestamp, $hook, $args ); ?> 

Note that scheduling an event to occur before 10 minutes after an existing event of the same name will be ignored, unless you pass unique values for $args to each scheduled event. See wp_next_scheduled() for more information.

This behavior is subject to change, as the original intention of the code was to prevent scheduling two identical events within ten minutes of each other, not preventing scheduling of identical events until ten minutes after the next scheduled occurrence.

Attempts to schedule an event after an event of the same name and $args will also be ignored.

Parameters

$timestamp

(integer) (required) The time you want the event to occur. This must be in a UNIX timestamp format. WP cron uses UTC/GMT time, not local time. Use time(), which is always GMT in WordPress. (current_time( 'timestamp' ) is local time in WordPress.)

Default: None

$hook

(string) (required) The name of an action hook to execute.

Default: None

$args

(array) (optional) Arguments to pass to the hook function(s)

Default: array()

Return Value

(boolean|null) 

False if the event was cancelled by a plugin, null otherwise.

Examples

Schedule an event one hour from now

function do_this_in_an_hour() {

    // do something
}
add_action( 'my_new_event','do_this_in_an_hour' );

// put this line inside a function, 
// presumably in response to something the user does
// otherwise it will schedule a new event on every page visit

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

// time() + 3600 = one hour from now.

Schedule an event one hour from now with arguments

function do_this_in_an_hour( $arg1, $arg2, $arg3 ) {
    // do something
}
add_action( 'my_new_event', 'do_this_in_an_hour', 10, 3 );

// put this line inside a function, 
// presumably in response to something the user does
// otherwise it will schedule a new event on every page visit

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

// time() + 3600 = one hour from now.

Notes

Wikipedia UNIX timestamp format

Change Log

Since: 2.1.0

Source File

wp_schedule_single_event() is located in wp-includes/cron.php

Related

Cron Functions: wp_schedule_event(), wp_schedule_single_event(), wp_clear_scheduled_hook(), wp_next_scheduled(), wp_unschedule_event(), wp_get_schedule()