wp_schedule_event

Schedule a recurring event.

Description

(false|void) wp_schedule_event( (int) $timestamp, (string) $recurrence, (string) $hook, (array) $args = array() ); 

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.

Valid values for the recurrence are hourly, daily, and twicedaily. These can be extended using the filter in wp_get_schedules().

Use wp_next_scheduled() to prevent duplicates

Returns (false|void)

False if the event does not get scheduled.

Parameters (4)

0. $timestamp (int)
Unix timestamp (UTC) for when to run the event.
1. $recurrence (string)
How often the event should recur.
2. $hook (string)
Action hook to execute when event is run.
3. $args — Optional. (array) => array()
Arguments to pass to the hook's callback function.

Usage

  1. if ( !function_exists( 'wp_schedule_event' ) ) { 
  2. require_once ABSPATH . WPINC . '/cron.php'; 
  3.  
  4. // Unix timestamp (UTC) for when to run the event. 
  5. $timestamp = -1; 
  6.  
  7. // How often the event should recur. 
  8. $recurrence = ''; 
  9.  
  10. // Action hook to execute when event is run. 
  11. $hook = ''; 
  12.  
  13. // Optional. Arguments to pass to the hook's callback function. 
  14. $args = array(); 
  15.  
  16. // NOTICE! Understand what this does before running. 
  17. $result = wp_schedule_event($timestamp, $recurrence, $hook, $args); 
  18.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/cron.php  
  1. function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array()) { 
  2. // Make sure timestamp is a positive integer 
  3. if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) { 
  4. return false; 
  5.  
  6. $crons = _get_cron_array(); 
  7. $schedules = wp_get_schedules(); 
  8.  
  9. if ( !isset( $schedules[$recurrence] ) ) 
  10. return false; 
  11.  
  12. $event = (object) array( 'hook' => $hook, 'timestamp' => $timestamp, 'schedule' => $recurrence, 'args' => $args, 'interval' => $schedules[$recurrence]['interval'] ); 
  13. /** This filter is documented in wp-includes/cron.php */ 
  14. $event = apply_filters( 'schedule_event', $event ); 
  15.  
  16. // A plugin disallowed this event 
  17. if ( ! $event ) 
  18. return false; 
  19.  
  20. $key = md5(serialize($event->args)); 
  21.  
  22. $crons[$event->timestamp][$event->hook][$key] = array( 'schedule' => $event->schedule, 'args' => $event->args, 'interval' => $event->interval ); 
  23. uksort( $crons, "strnatcasecmp" ); 
  24. _set_cron_array( $crons );