wp_schedule_event( int $timestamp, string $recurrence, string $hook, array $args = array() )

Schedule a recurring event.


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

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

Use wp_next_scheduled() to prevent duplicates


Parameters Parameters

$timestamp

(int) (Required) Unix timestamp (UTC) for when to run the event.

$recurrence

(string) (Required) How often the event should recur.

$hook

(string) (Required) Action hook to execute when event is run.

$args

(array) (Optional) Arguments to pass to the hook's callback function.

Default value: array()


Top ↑

Return Return

(false|void) False if the event does not get scheduled.


Top ↑

Source Source

File: wp-includes/cron.php

function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array()) {
	// Make sure timestamp is a positive integer
	if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
		return false;
	}

	$crons = _get_cron_array();
	$schedules = wp_get_schedules();

	if ( !isset( $schedules[$recurrence] ) )
		return false;

	$event = (object) array( 'hook' => $hook, 'timestamp' => $timestamp, 'schedule' => $recurrence, 'args' => $args, 'interval' => $schedules[$recurrence]['interval'] );
	/** This filter is documented in wp-includes/cron.php */
	$event = apply_filters( 'schedule_event', $event );

	// A plugin disallowed this event
	if ( ! $event )
		return false;

	$key = md5(serialize($event->args));

	$crons[$event->timestamp][$event->hook][$key] = array( 'schedule' => $event->schedule, 'args' => $event->args, 'interval' => $event->interval );
	uksort( $crons, "strnatcasecmp" );
	_set_cron_array( $crons );
}

Top ↑

Changelog Changelog

Changelog
Version Description
2.1.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note content
    Contributed by Sushil Adhikari

    Schedule hourly event with multiple arguments
    wp_schedule_event() pass arguments by reference, so we have to send multiple data as indexed array.

    register_activation_hook( __FILE__, 'my_activation' );
     
    function my_activation() {
    	$args = array( $args_1, $args_2 );
    	if (! wp_next_scheduled ( 'my_hourly_event', $args )) {
        	wp_schedule_event( time(), 'hourly', 'my_hourly_event', $args );
        }
    }

    Don’t forgot to add total number of argument as $accepted_args on add_action().

    add_action( 'my_hourly_event', 'do_this_hourly', 10, 2 );
    function do_this_hourly($args_1, $args_2 ) {
        // 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' );
    }
  2. Skip to note content
    Contributed by Codex

    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' );
    }

You must log in before being able to contribute a note or feedback.