WordPress.org

Ready to get started?Download WordPress

Codex

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

Difference between revisions of "Function Reference/wp schedule event"

m (Parameters: added note about creating custom intervals)
(Parameters: adding note about using current_time() instead of time())
Line 8: Line 8:
   
 
== Parameters ==
 
== Parameters ==
{{Parameter|$timestamp|integer|The first time that you want the event to occur. This must be in a UNIX timestamp format.}}
+
{{Parameter|$timestamp|integer|The first time that you want the event to occur. This must be in a UNIX timestamp format. You should use WordPress' [[Function_Reference/current_time|current_time( 'timestamp' )]] instead of PHP's time(); otherwise the first occurrence of the event will not be in your local time, which may lead to confusion.}}
 
{{Parameter|$recurrence|string|How often the event should reoccur. Valid values are below. You can create custom intervals using the cron_schedules filter in [[Function_Reference/wp_get_schedules|wp_get_schedules()]]. <ul><li><tt>hourly</tt></li><li><tt>twicedaily</tt></li><li><tt>daily</tt></li></ul>}}
 
{{Parameter|$recurrence|string|How often the event should reoccur. Valid values are below. You can create custom intervals using the cron_schedules filter in [[Function_Reference/wp_get_schedules|wp_get_schedules()]]. <ul><li><tt>hourly</tt></li><li><tt>twicedaily</tt></li><li><tt>daily</tt></li></ul>}}
 
{{Parameter|$hook|string|The name of an action hook to execute.}}
 
{{Parameter|$hook|string|The name of an action hook to execute.}}

Revision as of 20:00, 20 April 2012

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. You should use WordPress' current_time( 'timestamp' ) instead of PHP's time(); otherwise the first occurrence of the event will not be in your local time, which may lead to confusion.
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.
Default: None
$args
(array) (optional) Arguments to pass to the hook function(s).
Default: None

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__, 'my_activation');
add_action('my_hourly_event', 'do_this_hourly');

function my_activation() {
	wp_schedule_event(time(), 'hourly', 'my_hourly_event');
}

function do_this_hourly() {
	// do something every hour
}

Don't forget to clean the scheduler on deactivation:

register_deactivation_hook(__FILE__, 'my_deactivation');

function my_deactivation() {
	wp_clear_scheduled_hook('my_hourly_event');
}

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('my_hourly_event', 'do_this_hourly');

function my_activation() {
	if ( !wp_next_scheduled( 'my_hourly_event' ) ) {
		wp_schedule_event(time(), 'hourly', 'my_hourly_event');
	}
}
add_action('wp', 'my_activation');

function do_this_hourly() {
	// do something every hour
}

See Also

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.