Scheduling Tasks in WordPress: a Plugin Developer’s Guide

Before we look at how to set up scheduled tasks in your WordPressplugin, you need to understand how WordPress handles scheduled tasksbehind the scenes.Every time someone visits a page of the site, WordPress checks tosee if any of the functions that have been scheduled need to be executed.This is based on the interval since the last execution or the time whenthe task was scheduled.WordPress uses the fsockopen PHP functionto make a request to the wp-cron.php file that’slocated in the WordPress installation directory. To make sure that thewebsite visitor is unaffected by this call, the timeout for the request isvery small (0.1 seconds). Having initiated the request, WordPress doesn’twait for a response, and continues serving the page to the user. The 0.1second timeout is enough to initiate execution of thewp-cron.php file.The first statement the wp-cron.php fileexecutes is:

ignore_user_abort(true);

This ensures that execution continues, even if the client whorequested the page closes the connection (this would otherwise terminateexecution). This script will check for any tasks that should be run, basedon the current time and the time they were last executed. For example,let’s say you have a task that’s scheduled to run hourly, and was last runat 4:13 p.m. When a user requests a page from your site at 5:11 p.m.,wp-cron.php will skip your task, as it was last runless than an hour prior. A few minutes later, at 5:15 p.m., when anotheruser views a page, wp-cron.php will run yourtask.

In order to schedule a function to be run, either as a one-off taskor as a recurring task, you simply attach it to an action hook. Thisallows several functions to be assigned to the same scheduled hook. Incase you’re unfamiliar with WordPress action hooks, let’s do a quickreview before looking at how they’re applied to scheduling.If you’re already familiar with WordPress action hooks, feel free toskip this section and go straight to the section called “Scheduling Tasks”.

do_action('wp_head');

//This function generates the link tagfunction myplugin_generatestylesheet(){   //Form the URL to the css file stored in our plugin directory   $pluginURL = get_bloginfo('home').'/wp-content/plugins/myplugin/mycss.css';   //Write it to the browser   echo '<link href="'.$pluginURL.'" type="text/css" rel="stylesheet" />';}//Now we add this function to the wp_head action.add_action('wp_head','myplugin_generatestylesheet');

In WordPress, we can schedule functions to be called in twodifferent ways:

I’ll go over each of them in turn.

function my_function(){  // Do something. Anything.}

add_action('my_action','my_function');

wp_schedule_single_event($timestamp,'my_action');

function my_periodic_function(){  // Do something regularly.}

add_action('my_periodic_action','my_periodic_function');

wp_schedule_event($timestamp, 'hourly', 'my_periodic_action');

What if you need a recurrence period that’s shorter, such as everyfive minutes, or longer, such as once every month? In these cases, we candefine our own recurrence frequency and export it to WordPress. This isdone by attaching a function to the cron_schedulesfilter:

add_filter('cron_schedules','my_cron_definer');    function my_cron_definer($schedules){  $schedules['monthly'] = array(      'interval'=> 2592000,      'display'=>  __('Once Every 30 Days')  );  return $schedules;}

With this done, we can now use the new frequency when callingwp_schedule_event:

wp_schedule_event(time(),'monthly','my_action');

This will call my_action once every 30 days,starting from the current time.

Let’s say the administrator finds that their inbox keeps filling upwith backup emails when using our database backup plugin. Perhaps thedaily backup is overkill, considering the modest level of activity ontheir blog. So the admin logs into the WordPress dashboard and changes thebackup frequency to weekly instead of daily.In this scenario, the database plugin should change the frequency ofthe backup routine. Here we run into a bit of a roadblock: WordPress’sscheduling API doesn’t allow us to change the periodicity of a hook thathas already been scheduled. We need to first remove the daily schedule,and then attach a new weekly hook.

wp_clear_scheduled_hook('name_of_hook');

wp_unschedule_event($timestamp, $hook, $arguments);

$whenNext = wp_next_scheduled('my_action');wp_unschedule_event($whenNext,'my_action');

Now that you know how to schedule and unschedule tasks, you’re leftwith the question of whereabouts in your code to set up this schedule. Ifyour plugin should start the execution of the tasks immediately after theplugin is activated, the tasks must be registered within the activationhook. The activation hook is provided by WordPress, and is triggered whenthe plugin is first activated.When your plugin is deactivated, all tasks scheduled by your pluginshould be unscheduled. This makes sure that no duplicate tasks arescheduled by WordPress if your plugin is reactivated. This also ensuresthat any other plugin that makes use of the tasks scheduled by your plugindoesn’t produce undesired behavior.This very simple plugin demonstrates both the scheduling of taskswhen the plugin is activated, and their removal when the plugin isdeactivated:

<?php   /*   Plugin Name: My Plugin   Plugin URI: https://www.sitepoint.com/   Description: A plugin to learn crontasks.   Version: 2.9.2   Author: Raj Sekharan   Author URI: http://www.krusible.com   *//* The activation hook is executed when the plugin is activated. */register_activation_hook(__FILE__,'myplugin_activation');/* The deactivation hook is executed when the plugin is deactivated */register_deactivation_hook(__FILE__,'myplugin_deactivation');/* This function is executed when the user activates the plugin */function myplugin_activation(){  wp_schedule_event(time(), 'hourly', 'my_hook');}/* This function is executed when the user deactivates the plugin */function myplugin_deactivation(){  wp_clear_scheduled_hook('my_hook');}/* We add a function of our own to the my_hook action.add_action('my_hook','my_function');/* This is the function that is executed by the hourly recurring action my_hook */function my_function(){   //do something.}?>

While developing plugins that use scheduled tasks, it’s oftenhelpful to be able to see if the task has indeed been scheduled, andwhether it has been assigned the correct frequency. This can be done usingthe ControlCore plugin.The Control Core plugin was created to aid plugin developers intheir work, by providing control of certain aspects of the WordPress core.Control Core adds a section to the administration panel that shows all thetasks that are currently scheduled.

This method of scheduling tasks comes with a few warninglabels:

Although it’s possible to create WordPress plugins that performperiodic tasks without the WordPress scheduling API, it’s disadvantageousto do it that way. The procedure to set up your plugin will become morecomplicated, as the users will have to set up the crons manually.Complicated procedures only reduce the number of bloggers who can benefitfrom using your plugin.The setup process for a plugin should be as simple as clickingActivate in the Plugins section of the WordPressadministration panel. By making use of WordPress’s built-in schedulingfunctionality, you can give your plugins sophisticated features withoutmaking them more complicated to use.