WordPress operations like backup, security check, logs cleanup, email newsletters etc are automated so that they occur after every defined amount of time. These kind of operations are basically done using wordpress cron jobs which run a callback after a defined amount of time.
What Is WordPress Cron Jobs?
WordPress cron jobs is a set of wordpress APIs that lets you execute a PHP function after every constant interval of time. You can choose to make a event occur again and again or just once after a specified amount of time. This set of APIs expose a lot of other functionality which can be used to develop any kind of plugin or theme functionality which require scheduled events.
Accuracy of Cron Jobs
PHP code in servers is only executed when a page load occurs. Cron jobs in core are nothing but PHP code snippets which run if the scheduled time for the snippet is less than equal to the current time. Therefore if you schedule a callback(or event) at 10:00 AM then a pageload should occur at 10:00 AM or after 10:00 AM to call and execute the cron event.
Therefore Cron Jobs are not 100% accurate. In websites with huge traffic the accuracy reaches 99% but not 100%.
Cron Jobs don’t effect page load time because WordPress runs Cron Jobs asynchronously.
Scheduling events using wp_schedule_event
wp_schedule_event is used to schedule a event that will occur after every defined amount of time.
You have to call wp_schedule_event inside wp action.
Put this code in functions.php or plugin file.
//this action callback will be fired when event with the same name occurs
add_action("event_callback", "callback");
function callback(){
//send an email when event occurs
wp_email("to_email@qnimate.com", "Subject", "Email Body");
}
function schedule_cron_jobs()
{
//first arguement-> first time when the event will occur. Its in UNIX timestamp format.
//second arguement-> reoccurence instensity. Its value can be "hourly", "twicedaily" and "daily".
//thrid arguement-> name of the action hook whose callback will be fired when event occurs
//fourth arguement-> arguement to be passed to the callback.
wp_schedule_event(time(), "hourly", "event_callback", null);
}
add_action("wp", "schedule_cron_jobs");
?>
Cron Jobs always use UTC time they never use local time.
The above code may look fine but there is a problem. Every time wordpress sees the above code a new event is registered therefore if page load occures 100 times then 100 events will be registered. These causes the callback to be fired 100 times within a hour which is not what we want. We just want to register a event once and it should be fired after every specified amount of time.
Therefore before scheduling a event we need to check if the event is already scheduled or not.
add_action("event_callback", "callback");
function callback(){
wp_email("to_email@qnimate.com", "Subject", "Email Body");
}
function schedule_cron_jobs()
{
//check if a event with "event_callback" action hook registered or not
if(!wp_next_scheduled("event_callback"))
{
wp_schedule_event(time(), "hourly", "event_callback", null);
}
}
add_action("wp", "schedule_cron_jobs");
?>
Defining Custom Recurrence Timing
In the above example we had the choice to fire the event only after a hour, twice daily or once a day. What if we want to fire a event after every three and half hours? For this we need to create our own intervals called as cron job custom intervals.
//cron_schedules filter is used to create custom intervals
//$schedules arguement contains all the predefined and previously denfied intervals
add_filter("cron_schedules", function($schedules){
//add a new key to the $schedules. key name is same as custom interval name
//value is a array with interval recurrance seconds and textual description
$schedules["three_and_half_hours"] = array("interval" => 12600, "display" => "Three and half hours");
return $schedules;
});
add_action("event_callback", "callback");
function callback(){
//send an email when event occurs
wp_email("to_email@qnimate.com", "Subject", "Email Body");
}
function schedule_cron_jobs()
{
//check if a event with "event_callback" action hook registered or not
if(!wp_next_scheduled("event_callback"))
{
wp_schedule_event(time(), "three_and_half_hours", "event_callback", null);
}
}
add_action("wp", "schedule_cron_jobs");
?>
Unschedule Events using wp_unschedule_event
wp_unschedule_event is used to unschedule a scheduled event. It needs the next execution time and event name.
//first find the next schedule callback time
$time_next_firing = wp_next_scheduled("event_callback");
//use this function to unschedule it by passing the time and event name
wp_unschedule_event($time_next_firing, "event_callback");
?>
Retrieving list of scheduled events
wp_get_schedules and _get_cron_array is used to retrieve list of scheduled events by all plugins and theme. These both return a different set of data regarding the scheduled events.
$cron = _get_cron_array();
foreach ($cron as $time => $hook_name)
{
echo "<h1>".$time."</h1>";
print_r($hook_name);
}
$schedules = wp_get_schedules();
foreach ($schedules as $name)
{
echo "<h1>" . $name["display"] . ": " . $name["interval"] . "</h1>";
}
?>
Scheduling single events using wp_schedule_single_event
wp_schedule_single_event is used to schedule events that will be fired only once after a specified interval of time. They don’t reoccur.
add_action("event_callback", "callback");
function callback(){
wp_email("to_email@qnimate.com", "Subject", "Email Body");
}
function schedule_cron_jobs()
{
if(!wp_next_scheduled("event_callback"))
{
//first argument is the time after which the event will be fired
//name of the action hook whose callback will be executed.
wp_schedule_single_event(time() + 12600, "event_callback");
}
}
add_action("wp", "schedule_cron_jobs");
?>
Manually triggering scheduled events
do_action function is used to execute callback of any action. We can use this function to manually trigger any scheduled event anytime.
add_action("event_callback", function(){
wp_email("to_email@qnimate.com", "Subject", "Email Body");
})
//pass the action name
do_action("event_callback");
?>
@narayanprusty
