WordPress 5.1 sees a number of developer focused changes to the Cron API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.. These changes were discussed and made in #21072, #32656, #45797, and #45976.
Meaningful return values
Prior to WordPress 5.1, the functions used to modify scheduled tasks would return ambiguous values. These now return values indicating whether the function call was successful or otherwise.
wp_schedule_single_event(), wp_schedule_event(), wp_reschedule_event() and wp_unschedule_event() each return true or false to indicate whether the cron schedule was successfully modified.
wp_clear_scheduled_hook() and wp_unschedule_hook() each return false if the update was unsuccessful, 0 if there were no events to unschedule or an integer indicating the number of events that were successfully deleted.
Return values have also been added to the functions predominantly for use by WordPress Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. only: spawn_cron(), wp_cron(), and _set_cron_array().
New Functions
Two new functions have been added to assist with returning data.
wp_get_ready_cron_jobs(): retrieve cron jobs ready to be run.
Returns the results of _get_cron_array() limited to events ready to be run, ie, with a timestamp in the past. The new function returns the data only, it does not cause them to be run; that remains the role of other functions.
This function does not accept any arguments.
For more information, check out the source code for this function.
wp_get_scheduled_event(): retrieve a scheduled event.
Returns the full event object for a scheduled event.
The new function accepts three arguments:
$hook (string) Required, the action hook of the event.$args (array) Optional. An array containing each separate argument to pass to the hook’s callback function.$timestamp (integer or null) Optional. Unix timestamp (UTC) of the event. If not specified, the next scheduled event is returned.
The return value will be either the event object or false if the specified event has not been registered.
For more information, check out the source code for this function.
New filters for modifying cron storage
WordPress Core stores all cron events as an array in a single option. As the number of events increases, this method of storage can become somewhat unwieldy and unperformant.
In WordPress 5.1 writing a custom storage system for cron events will become substantially easier with filters added to each of the functions used for scheduling, re-scheduling, cancelling and returning a list of events.
Each of these hooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. follows the pattern of bypassing the Core function if the filter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. returns a value other than null.
Unless you are writing your own system for storing Cron jobs, these hooks are best left unused. If you are writing a custom storage solution, you will need to use all of them.
Each hook can be used to hijack the following:
pre_schedule_event for both single and recurring events,pre_reschedule_event for rescheduling an event,pre_unschedule_event for unscheduling an eventpre_clear_scheduled_hook for unscheduling all events attached to a hook/argument combinationpre_unschedule_hook for unscheduling all events related to a hookpre_get_scheduled_event for returning an event including by specifying its timestamp,pre_get_ready_cron_jobs for returning all cron events that are ready to be run
Warning: Adding code to these hooks must be done very early, before any other plugins attempt to register cron events or WordPress attempts to run any scheduled cron events on the init action.
Therefore, it is recommended you run add_filter() as your plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party is included , rather than waiting for the plugins_loaded or muplugins_loaded actions to fire. For example:
// File name: my-cron-plugin/my-cron-plugin.php
// Bootstrap immediately.
add_filter( 'pre_schedule_event', 'mcp_schedule_event', 10, 2 );
/**
* Use custom storage solution for scheduling Cron jobs.
*/
function mcp_schedule_event( $hijack, $event ) {
if ( $hijack !== null ) {
// Already hijacked.
return $hijack;
}
// Use my plugin's custom storage solution.
return true; // or false.
}
Note: WordPress 5.1 Beta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 1 and 2 included the filters pre_next_scheduled and next_scheduled in the function wp_next_scheduled(). These were later removed as the logic for returning the next scheduled event was moved to wp_get_scheduled_event() to improve performance.
#5-1, #dev-notes
You must be logged in to post a comment.