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 event

Contents

Description

Schedules a hook which will be executed by the WordPress actions core on a specific interval, specified by you. The action will trigger when someone visits your WordPress site, if the scheduled time has passed. See the Plugin API for a list of hooks.

Usage

 <?php wp_schedule_event($timestamp$recurrence$hook$args); ?> 

Parameters

$timestamp
(integer) (required) The first time that 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
$recurrence
(string) (required) How often the event should reoccur. Valid values are below. You can create custom intervals using the cron_schedules filter in wp_get_schedules().
  • hourly
  • twicedaily
  • daily
Default: None
$hook
(string) (required) The name of an action hook to execute. For some reason there seems to be a problem on some systems where the hook must not contain underscores or uppercase characters.
Default: None
$args
(array) (optional) Arguments to pass to the hook function(s).
Default: None

Return Value

(boolean|null) 
False on failure, null when complete with scheduling event.

Examples

Schedule an hourly event

To schedule an hourly event in a plugin, call wp_schedule_event on activation (otherwise you will end up with a lot of scheduled events!):

register_activation_hook( __FILE__, 'prefix_activation' );
/**
 * On activation, set a time, frequency and name of an action hook to be scheduled.
 */
function prefix_activation() {
	wp_schedule_event( time(), 'hourly', 'prefix_hourly_event_hook' );
}

add_action( 'prefix_hourly_event_hook', 'prefix_do_this_hourly' );
/**
 * On the scheduled action hook, run the function.
 */
function prefix_do_this_hourly() {
	// do something every hour
}

Don't forget to clean the scheduler on deactivation:

register_deactivation_hook( __FILE__, 'prefix_deactivation' );
/**
 * On deactivation, remove all functions from the scheduled action hook.
 */
function prefix_deactivation() {
	wp_clear_scheduled_hook( 'prefix_hourly_event_hook' );
}

A simple way to schedule an hourly event

This example doesn't rely on plugin activation (via the plugins directory) rather it simply adds the event if it is missing.

add_action( 'wp', 'prefix_setup_schedule' );
/**
 * On an early action hook, check if the hook is scheduled - if not, schedule it.
 */
function prefix_setup_schedule() {
	if ( ! wp_next_scheduled( 'prefix_hourly_event' ) ) {
		wp_schedule_event( time(), 'hourly', 'prefix_hourly_event');
	}
}


add_action( 'prefix_hourly_event', 'prefix_do_this_hourly' );
/**
 * On the scheduled action hook, run a function.
 */
function prefix_do_this_hourly() {
	// do something every hour
}

Notes

The array passed as the $args parameter needs to be an indexed array. Each element in the array is sliced into a separate argument in the do_action_ref_array() call. Despite the name, your array is not passed by reference.

When you add the action that calls your scheduled function, you must specify a priority and the number of elements in the array. Your scheduled function declaration must accept each array element as individual parameters

Example passing multiple arguments

add_action('wp', 'prefix_setup_schedule');
function prefix_setup_schedule() {
	if ( ! wp_next_scheduled('prefix_hourly_event')) {
		wp_schedule_event( time(), 'hourly', 'prefix_hourly_event',
			array( 'example', 'values')
		);
	}
}

add_action('prefix_hourly_event', 'prefix_do_this_hourly', 10 ,2 );
function prefix_do_this_hourly( $parm1, $parm2 ) {
	error_log("Function prefix_do_this_hourly() received '$parm1' and '$parm2' as parameters.");
}
// PHP error log will have this line entered every hour:
//   Function prefix_do_this_hourly() received 'example' and 'values' as parameters.

Cron Data

Cron data is saved to the options table. Use get_option('cron'); to get the cron array from the database.

Change Log

Since: 2.1.0

Source File

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

Related

Further Reading

For a comprehensive list of functions, take a look at the category Functions

Also, see Function_Reference

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