wp_schedule_single_event() – all about scheduling one-time events with working examples

Updated on June 5, 2021

With this function I open the new post series about WordPress Cron. I don’t want to create the common post about all the cron functions, so we will look at each function separately.

Before we begin. UNIX time format.

To work with WP Cron you should know about this time format a little. UNIX time is the seconds that passed since January 1, 1970.

And let’s look at examples.

/*
 * time() prints the current UNIX-time
 * the result will be different each time you refresh the page (because the time is in seconds)
 */
echo time(); // 1454835955

/*
 * using date() function you can easily convert UNIX time into another time format
 * by the way, the second argument of the date() function by default is the value of time() function
 */
echo date('Y-m-d', 1454835955); // 2016-02-07 (year-month-day)
echo date('F j, Y H:i', 1454835955); // February 7, 2016 13:10

/*
 * I love strtotime() function, it allows to convert different time string representations into UNIX-time format.
 */
echo strtotime( '2016-02-07' ); // 1454788800
echo strtotime( '+1 day' ) // tomorrow at the same time
echo strtotime( '-2 day' ) // the day before yesterday at the same time (you can use plural forms or not)
echo strtotime( '+1 year 3 months 1 week 3 days 2 hours 30 minutes 55 seconds' ); // everything you ever wanted
echo strtotime( 'next Sunday' ); // next Sunday
echo strtotime( 'last Monday' ); // the previous Monday

I think it will be enough to work with WP Cron.

wp_schedule_single_event()


wp_schedule_single_event( $timestamp, $hook, $args = array() )

$timestamp

(int) Date and time in the UNIX format when the function will run.

One important thing. The less visitors your website has the lower chance that scheduled task will be run exactly in time. How this works — someone goes to a website page, after that all the tasks with the passed scheduled time will be executed.

$hook

(string) Name of the action hook the wp_schedule_single_event() will fire. All the functions that connected to this hook will be fired as well.

You should know that wp_schedule_single_event() will return false and won’t schedule the next task if the previous scheduled identical event doesn’t run in the next 10 minutes.

But this rule doesn’t work if you specify some unique values in the third function parameter.

$args

(array) The array of values that will be passed into the hook and into all the connected functions as well.

So, you can schedule much more action hooks with the same name but with the different parameters.

Working Examples

1. How to change admin email in a 10 minutes after switching a theme

I have no idea if this function could be helpful but my purpose is to show the WP Cron process in action in a very easy way. So, just insert the following code to you theme functions.php.

// this function will change the email in General Settings
function rudr_change_email_in_10_min() {
	update_option('admin_email','no-reply@rudrastyh.com');
}

// that's the action hook which will be executed in a 10 minutes
add_action( 'rudr_my_hook', 'rudr_change_email_in_10_min' );

// I do not want this event to schedule each time the page is refreshed, so let's make it to schedule after switching a theme
if( $_GET['activated'] == 'true' )
	wp_schedule_single_event( time() + 600, 'rudr_my_hook' ); // 600 second and 10 minutes is the same, if you do not know :)

Now just change your current theme and change it back again. Then after 10 minutes go to General settings and view the result.

2. Remove the exact post by its ID in a 5 minutes and then after another 5 minutes remove the another post.

For this example you will need two posts you can remove from you website (in fact we just move that posts to trash, so you could restore them).

In this example I don’t create a new function, I just hook the WordPress default wp_trash_post().

// the last action hook parameter is the number of arguments used, we have just one - post ID, the wp_trash_post() function also accept the single parameter!
add_action( 'rudr_hook_2', 'wp_trash_post', 10, 1 );
 
if( $_GET['activated'] == 'true' ) {
	// we have to remove two posts ( e.g. with ID=2 and ID=5 )
	wp_schedule_single_event( time() + 300, 'rudr_hook_2', array( 2 ) );
	wp_schedule_single_event( strtotime('+10 minutes'), 'rudr_hook_2', array( 5 ) ); // you can use strtotime()
}

3. How to view and cotrol scheduled tasks in WordPress

If you already run the code from the previuos example and you’re waiting 10 minutes when both posts will be removed, you can make a look at you tasks.

You can do it with the code:

$wp_cron_tasks = get_option( 'cron' );
var_dump( $wp_cron_tasks );

Or with the Advanced Cron Manager plugin. Add it via /wp-admin/ then go to Tools > Cron Manager and you will see:

You can easily view all your scheduled events with the Advanced Cron Manager plugin.

4. How to unschedule the event.

We will continue to work with the previous example. Let’s unschedule the rudr_hook_2 event with argument value 5. You can do it easily with the help of the wp_clear_scheduled_hook() function. Do not forget to pass the same argument values.

wp_clear_scheduled_hook( 'rudr_hook_2', array( 5 ) );

As with the previous functions from this post, it is not recommended to use wp_clear_scheduled_hook() directly in functions.php (it shouldn’t be run each time the page is refreshed). Remember that.

# WordPress