WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/wp schedule single event

Contents

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.
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

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()

See also index of Function Reference and index of Template Tags.