<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[43540] trunk: Cron: Add hooks and a function to allow hijacking cron implementation.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { white-space: pre-line; overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="https://core.trac.wordpress.org/changeset/43540">43540</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"https://core.trac.wordpress.org/changeset/43540","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>peterwilsoncc</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2018-07-27 02:22:50 +0000 (Fri, 27 Jul 2018)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>Cron: Add hooks and a function to allow hijacking cron implementation.
This allows sites with a large cron option or a custom cron implementation to hijack the cron option to store cron data using custom functionality.
`wp_get_scheduled_event()` is new function to retrieve the event object for a given event based on the hook name, arguments and timestamp. If no timestamp is specified the next occurence is returned.
Preflight filters are added to all functions that read from or modify the cron option: `pre_schedule_event`, `pre_reschedule_event`, `pre_unschedule_event`, `pre_clear_scheduled_hook`, `pre_unschedule_hook`, `pre_get_scheduled_event` and `pre_next_scheduled`.
Additionally, the post scheduling hooks `next_scheduled` and `get_schedule` to allow plugins to modify an event after retrieving it from WordPress.
Props rmccue, DavidAnderson, ethitter, peterwilsoncc.
Fixes <a href="https://core.trac.wordpress.org/ticket/32656">#32656</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludescronphp">trunk/src/wp-includes/cron.php</a></li>
<li><a href="#trunktestsphpunittestscronphp">trunk/tests/phpunit/tests/cron.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludescronphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/cron.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/cron.php 2018-07-26 22:55:29 UTC (rev 43539)
+++ trunk/src/wp-includes/cron.php 2018-07-27 02:22:50 UTC (rev 43540)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -21,7 +21,8 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * Use wp_schedule_event() to schedule a recurring event.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 2.1.0
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @since 5.0.0 Return value modified to boolean indicating success or failure.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @since 5.0.0 Return value modified to boolean indicating success or failure,
+ * {@see pre_schedule_event} filter added to short-circuit the function.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @link https://codex.wordpress.org/Function_Reference/wp_schedule_single_event
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -36,13 +37,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // Don't schedule a duplicate if there's already an identical event due within 10 minutes of it
- $next = wp_next_scheduled( $hook, $args );
- if ( $next && abs( $next - $timestamp ) <= 10 * MINUTE_IN_SECONDS ) {
- return false;
- }
-
- $crons = _get_cron_array();
</del><span class="cx" style="display: block; padding: 0 10px"> $event = (object) array(
</span><span class="cx" style="display: block; padding: 0 10px"> 'hook' => $hook,
</span><span class="cx" style="display: block; padding: 0 10px"> 'timestamp' => $timestamp,
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -51,6 +45,47 @@
</span><span class="cx" style="display: block; padding: 0 10px"> );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> /**
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Filter to preflight or hijack scheduling an event.
+ *
+ * Returning a non-null value will short-circuit adding the event to the
+ * cron array, causing the function to return the filtered value instead.
+ *
+ * Both single events and recurring events are passed through this filter;
+ * single events have `$event->schedule` as false, whereas recurring events
+ * have this set to a recurrence from {@see wp_get_schedules}. Recurring
+ * events also have the integer recurrence interval set as `$event->interval`.
+ *
+ * For plugins replacing wp-cron, it is recommended you check for an
+ * identical event within ten minutes and apply the {@see schedule_event}
+ * filter to check if another plugin has disallowed the event before scheduling.
+ *
+ * Return true if the event was scheduled, false if not.
+ *
+ * @since 5.0.0
+ *
+ * @param null|bool $pre Value to return instead. Default null to continue adding the event.
+ * @param stdClass $event {
+ * An object containing an event's data.
+ *
+ * @type string $hook Action hook to execute when the event is run.
+ * @type int $timestamp Unix timestamp (UTC) for when to next run the event.
+ * @type string|false $schedule How often the event should subsequently recur.
+ * @type array $args Array containing each separate argument to pass to the hook's callback function.
+ * @type int $interval The interval time in seconds for the schedule. Only present for recurring events.
+ * }
+ */
+ $pre = apply_filters( 'pre_schedule_event', null, $event );
+ if ( null !== $pre ) {
+ return $pre;
+ }
+
+ // Don't schedule a duplicate if there's already an identical event due within 10 minutes of it
+ $next = wp_next_scheduled( $hook, $args );
+ if ( $next && abs( $next - $timestamp ) <= 10 * MINUTE_IN_SECONDS ) {
+ return false;
+ }
+
+ /**
</ins><span class="cx" style="display: block; padding: 0 10px"> * Filters a single event before it is scheduled.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 3.1.0
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -74,6 +109,7 @@
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> $key = md5( serialize( $event->args ) );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $crons = _get_cron_array();
</ins><span class="cx" style="display: block; padding: 0 10px"> $crons[ $event->timestamp ][ $event->hook ][ $key ] = array(
</span><span class="cx" style="display: block; padding: 0 10px"> 'schedule' => $event->schedule,
</span><span class="cx" style="display: block; padding: 0 10px"> 'args' => $event->args,
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -101,7 +137,8 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * Use wp_schedule_single_event() to schedule a non-recurring event.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 2.1.0
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @since 5.0.0 Return value modified to boolean indicating success or failure.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @since 5.0.0 Return value modified to boolean indicating success or failure,
+ * {@see pre_schedule_event} filter added to short-circuit the function.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @link https://codex.wordpress.org/Function_Reference/wp_schedule_event
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -117,7 +154,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $crons = _get_cron_array();
</del><span class="cx" style="display: block; padding: 0 10px"> $schedules = wp_get_schedules();
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> if ( ! isset( $schedules[ $recurrence ] ) ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -131,7 +167,14 @@
</span><span class="cx" style="display: block; padding: 0 10px"> 'args' => $args,
</span><span class="cx" style="display: block; padding: 0 10px"> 'interval' => $schedules[ $recurrence ]['interval'],
</span><span class="cx" style="display: block; padding: 0 10px"> );
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
</ins><span class="cx" style="display: block; padding: 0 10px"> /** This filter is documented in wp-includes/cron.php */
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $pre = apply_filters( 'pre_schedule_event', null, $event );
+ if ( null !== $pre ) {
+ return $pre;
+ }
+
+ /** This filter is documented in wp-includes/cron.php */
</ins><span class="cx" style="display: block; padding: 0 10px"> $event = apply_filters( 'schedule_event', $event );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> // A plugin disallowed this event
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -141,6 +184,7 @@
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> $key = md5( serialize( $event->args ) );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $crons = _get_cron_array();
</ins><span class="cx" style="display: block; padding: 0 10px"> $crons[ $event->timestamp ][ $event->hook ][ $key ] = array(
</span><span class="cx" style="display: block; padding: 0 10px"> 'schedule' => $event->schedule,
</span><span class="cx" style="display: block; padding: 0 10px"> 'args' => $event->args,
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -154,7 +198,8 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * Reschedules a recurring event.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 2.1.0
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @since 5.0.0 Return value modified to boolean indicating success or failure.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @since 5.0.0 Return value modified to boolean indicating success or failure,
+ * {@see pre_reschedule_event} filter added to short-circuit the function.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param int $timestamp Unix timestamp (UTC) for when to next run the event.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $recurrence How often the event should subsequently recur. See wp_get_schedules() for accepted values.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -168,19 +213,57 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $crons = _get_cron_array();
</del><span class="cx" style="display: block; padding: 0 10px"> $schedules = wp_get_schedules();
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $key = md5( serialize( $args ) );
</del><span class="cx" style="display: block; padding: 0 10px"> $interval = 0;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // First we try to get it from the schedule
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // First we try to get the interval from the schedule.
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( isset( $schedules[ $recurrence ] ) ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $interval = $schedules[ $recurrence ]['interval'];
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // Now we try to get it from the saved interval in case the schedule disappears
- if ( 0 == $interval ) {
- $interval = $crons[ $timestamp ][ $hook ][ $key ]['interval'];
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // Now we try to get it from the saved interval in case the schedule disappears.
+ if ( 0 === $interval ) {
+ $scheduled_event = wp_get_scheduled_event( $hook, $args, $timestamp );
+ if ( $scheduled_event && isset( $scheduled_event->interval ) ) {
+ $interval = $scheduled_event->interval;
+ }
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ $event = (object) array(
+ 'hook' => $hook,
+ 'timestamp' => $timestamp,
+ 'schedule' => $recurrence,
+ 'args' => $args,
+ 'interval' => $interval,
+ );
+
+ /**
+ * Filter to preflight or hijack rescheduling of events.
+ *
+ * Returning a non-null value will short-circuit the normal rescheduling
+ * process, causing the function to return the filtered value instead.
+ *
+ * For plugins replacing wp-cron, return true if the event was successfully
+ * rescheduled, false if not.
+ *
+ * @since 5.0.0
+ *
+ * @param null|bool $pre Value to return instead. Default null to continue adding the event.
+ * @param stdClass $event {
+ * An object containing an event's data.
+ *
+ * @type string $hook Action hook to execute when the event is run.
+ * @type int $timestamp Unix timestamp (UTC) for when to next run the event.
+ * @type string|false $schedule How often the event should subsequently recur.
+ * @type array $args Array containing each separate argument to pass to the hook's callback function.
+ * @type int $interval The interval time in seconds for the schedule. Only present for recurring events.
+ * }
+ */
+ $pre = apply_filters( 'pre_reschedule_event', null, $event );
+ if ( null !== $pre ) {
+ return $pre;
+ }
+
</ins><span class="cx" style="display: block; padding: 0 10px"> // Now we assume something is wrong and fail to schedule
</span><span class="cx" style="display: block; padding: 0 10px"> if ( 0 == $interval ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -204,7 +287,8 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * identified.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 2.1.0
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @since 5.0.0 Return value modified to boolean indicating success or failure.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @since 5.0.0 Return value modified to boolean indicating success or failure,
+ * {@see pre_unschedule_event} filter added to short-circuit the function.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param int $timestamp Unix timestamp (UTC) of the event.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $hook Action hook of the event.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -219,6 +303,27 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Filter to preflight or hijack unscheduling of events.
+ *
+ * Returning a non-null value will short-circuit the normal unscheduling
+ * process, causing the function to return the filtered value instead.
+ *
+ * For plugins replacing wp-cron, return true if the event was successfully
+ * unscheduled, false if not.
+ *
+ * @since 5.0.0
+ *
+ * @param null|bool $pre Value to return instead. Default null to continue unscheduling the event.
+ * @param int $timestamp Timestamp for when to run the event.
+ * @param string $hook Action hook, the execution of which will be unscheduled.
+ * @param array $args Arguments to pass to the hook's callback function.
+ */
+ $pre = apply_filters( 'pre_unschedule_event', null, $timestamp, $hook, $args );
+ if ( null !== $pre ) {
+ return $pre;
+ }
+
</ins><span class="cx" style="display: block; padding: 0 10px"> $crons = _get_cron_array();
</span><span class="cx" style="display: block; padding: 0 10px"> $key = md5( serialize( $args ) );
</span><span class="cx" style="display: block; padding: 0 10px"> unset( $crons[ $timestamp ][ $hook ][ $key ] );
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -240,7 +345,8 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * the `===` operator for testing the return value of this function.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 2.1.0
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @since 5.0.0 Return value modified to indicate success or failure.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @since 5.0.0 Return value modified to indicate success or failure,
+ * {@see pre_clear_scheduled_hook} filter added to short-circuit the function.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $hook Action hook, the execution of which will be unscheduled.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param array $args Optional. Arguments that were to be passed to the hook's callback function.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -256,6 +362,27 @@
</span><span class="cx" style="display: block; padding: 0 10px"> $args = array_slice( func_get_args(), 1 );
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Filter to preflight or hijack clearing a scheduled hook.
+ *
+ * Returning a non-null value will short-circuit the normal unscheduling
+ * process, causing the function to return the filtered value instead.
+ *
+ * For plugins replacing wp-cron, return the number of events successfully
+ * unscheduled (zero if no events were registered with the hook) or false
+ * if unscheduling one or more events fails.
+ *
+ * @since 5.0.0
+ *
+ * @param null|array $pre Value to return instead. Default null to continue unscheduling the event.
+ * @param string $hook Action hook, the execution of which will be unscheduled.
+ * @param array $args Arguments to pass to the hook's callback function.
+ */
+ $pre = apply_filters( 'pre_clear_scheduled_hook', null, $hook, $args );
+ if ( null !== $pre ) {
+ return $pre;
+ }
+
</ins><span class="cx" style="display: block; padding: 0 10px"> // This logic duplicates wp_next_scheduled()
</span><span class="cx" style="display: block; padding: 0 10px"> // It's required due to a scenario where wp_unschedule_event() fails due to update_option() failing,
</span><span class="cx" style="display: block; padding: 0 10px"> // and, wp_next_scheduled() returns the same schedule in an infinite loop.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -295,6 +422,26 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * events were registered on the hook), false if unscheduling fails.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function wp_unschedule_hook( $hook ) {
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Filter to preflight or hijack clearing all events attached to the hook.
+ *
+ * Returning a non-null value will short-circuit the normal unscheduling
+ * process, causing the function to return the filtered value instead.
+ *
+ * For plugins replacing wp-cron, return the number of events successfully
+ * unscheduled (zero if no events were registered with the hook) or false
+ * if unscheduling one or more events fails.
+ *
+ * @since 5.0.0
+ *
+ * @param null|array $pre Value to return instead. Default null to continue unscheduling the hook.
+ * @param string $hook Action hook, the execution of which will be unscheduled.
+ */
+ $pre = apply_filters( 'pre_unschedule_hook', null, $hook );
+ if ( null !== $pre ) {
+ return $pre;
+ }
+
</ins><span class="cx" style="display: block; padding: 0 10px"> $crons = _get_cron_array();
</span><span class="cx" style="display: block; padding: 0 10px"> if ( empty( $crons ) ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return 0;
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -326,9 +473,79 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> /**
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Retrieve a scheduled event.
+ *
+ * Retrieve the full event object for a given event.
+ *
+ * @since 5.0.0
+ *
+ * @param string $hook Action hook of the event.
+ * @param array $args Optional. Array containing each separate argument to pass to the hook's callback function.
+ * Although not passed to a callback, these arguments are used to uniquely identify the
+ * event, so they should be the same as those used when originally scheduling the event.
+ * @param int|null $timestamp Optional. Unix timestamp (UTC) of the event. If not specified, the next scheduled event is returned.
+ * @return bool|object The event object. False if the event does not exist.
+ */
+function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) {
+ if ( ! $timestamp ) {
+ // Get the next scheduled event.
+ $timestamp = wp_next_scheduled( $hook, $args );
+ }
+
+ /**
+ * Filter to preflight or hijack retrieving a scheduled event.
+ *
+ * Returning a non-null value will short-circuit the normal process,
+ * returning the filtered value instead.
+ *
+ * Return false if the event does not exist, otherwise an event object
+ * should be returned.
+ *
+ * @since 5.0.0
+ *
+ * @param null|bool $pre Value to return instead. Default null to continue retrieving the event.
+ * @param string $hook Action hook of the event.
+ * @param array $args Array containing each separate argument to pass to the hook's callback function.
+ * Although not passed to a callback, these arguments are used to uniquely identify the
+ * event.
+ * @param int $timestamp Unix timestamp (UTC) of the event.
+ */
+ $pre = apply_filters( 'pre_get_scheduled_event', null, $hook, $args, $timestamp );
+ if ( null !== $pre ) {
+ return $pre;
+ }
+
+ $crons = _get_cron_array();
+ $key = md5( serialize( $args ) );
+
+ if ( ! $timestamp || ! isset( $crons[ $timestamp ] ) ) {
+ // No such event.
+ return false;
+ }
+
+ if ( ! isset( $crons[ $timestamp ][ $hook ] ) || ! isset( $crons[ $timestamp ][ $hook ][ $key ] ) ) {
+ return false;
+ }
+
+ $event = (object) array(
+ 'hook' => $hook,
+ 'timestamp' => $timestamp,
+ 'schedule' => $crons[ $timestamp ][ $hook ][ $key ]['schedule'],
+ 'args' => $args,
+ );
+
+ if ( isset( $crons[ $timestamp ][ $hook ][ $key ]['interval'] ) ) {
+ $event->interval = $crons[ $timestamp ][ $hook ][ $key ]['interval'];
+ }
+
+ return $event;
+}
+
+/**
</ins><span class="cx" style="display: block; padding: 0 10px"> * Retrieve the next timestamp for an event.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 2.1.0
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @since 5.0.0 {@see pre_next_scheduled} and {@see next_scheduled} filters added.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $hook Action hook of the event.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param array $args Optional. Array containing each separate argument to pass to the hook's callback function.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -337,17 +554,48 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @return false|int The Unix timestamp of the next time the event will occur. False if the event doesn't exist.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function wp_next_scheduled( $hook, $args = array() ) {
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Filter to preflight or hijack retrieving the next scheduled event timestamp.
+ *
+ * Returning a non-null value will short-circuit the normal retrieval
+ * process, causing the function to return the filtered value instead.
+ *
+ * Pass the timestamp of the next event if it exists, false if not.
+ *
+ * @since 5.0.0
+ *
+ * @param null|bool $pre Value to return instead. Default null to continue unscheduling the event.
+ * @param string $hook Action hook of the event.
+ * @param array $args Arguments to pass to the hook's callback function.
+ */
+ $pre = apply_filters( 'pre_next_scheduled', null, $hook, $args );
+ if ( null !== $pre ) {
+ return $pre;
+ }
+
</ins><span class="cx" style="display: block; padding: 0 10px"> $crons = _get_cron_array();
</span><span class="cx" style="display: block; padding: 0 10px"> $key = md5( serialize( $args ) );
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- if ( empty( $crons ) ) {
- return false;
- }
- foreach ( $crons as $timestamp => $cron ) {
- if ( isset( $cron[ $hook ][ $key ] ) ) {
- return $timestamp;
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $next = false;
+
+ if ( ! empty( $crons ) ) {
+ foreach ( $crons as $timestamp => $cron ) {
+ if ( isset( $cron[ $hook ][ $key ] ) ) {
+ $next = $timestamp;
+ break;
+ }
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- return false;
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ /**
+ * Filter the next scheduled event timestamp.
+ *
+ * @since 5.0.0
+ *
+ * @param int|bool $next The UNIX timestamp when the scheduled event will next occur, or false if not found.
+ * @param string $hook Action hook to execute when cron is run.
+ * @param array $args Arguments to be passed to the callback function. Used for deduplicating events.
+ */
+ return apply_filters( 'next_scheduled', $next, $hook, $args );
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> /**
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -572,6 +820,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @see wp_get_schedules() for available schedules.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 2.1.0
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @since 5.0.0 {@see get_schedule} filter added.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $hook Action hook to identify the event.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param array $args Optional. Arguments passed to the event's callback function.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -578,17 +827,23 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @return string|false False, if no schedule. Schedule name on success.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function wp_get_schedule( $hook, $args = array() ) {
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $crons = _get_cron_array();
- $key = md5( serialize( $args ) );
- if ( empty( $crons ) ) {
- return false;
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $schedule = false;
+ $event = wp_get_scheduled_event( $hook, $args );
+
+ if ( $event ) {
+ $schedule = $event->schedule;
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- foreach ( $crons as $timestamp => $cron ) {
- if ( isset( $cron[ $hook ][ $key ] ) ) {
- return $cron[ $hook ][ $key ]['schedule'];
- }
- }
- return false;
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ /**
+ * Filter the schedule for a hook.
+ *
+ * @since 5.0.0
+ *
+ * @param string|bool $schedule Schedule for the hook. False if not found.
+ * @param string $hook Action hook to execute when cron is run.
+ * @param array $args Optional. Arguments to pass to the hook's callback function.
+ */
+ return apply_filters( 'get_schedule', $schedule, $hook, $args );
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> //
</span></span></pre></div>
<a id="trunktestsphpunittestscronphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/tests/phpunit/tests/cron.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/tests/phpunit/tests/cron.php 2018-07-26 22:55:29 UTC (rev 43539)
+++ trunk/tests/phpunit/tests/cron.php 2018-07-27 02:22:50 UTC (rev 43540)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -6,10 +6,22 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @group cron
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> class Tests_Cron extends WP_UnitTestCase {
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @var array Cron array for testing preflight filters.
+ */
+ private $preflight_cron_array;
+
+ /**
+ * @var int Timestamp of now() + 30 minutes;
+ */
+ private $plus_thirty_minutes;
+
</ins><span class="cx" style="display: block; padding: 0 10px"> function setUp() {
</span><span class="cx" style="display: block; padding: 0 10px"> parent::setUp();
</span><span class="cx" style="display: block; padding: 0 10px"> // make sure the schedule is clear
</span><span class="cx" style="display: block; padding: 0 10px"> _set_cron_array( array() );
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $this->preflight_cron_array = array();
+ $this->plus_thirty_minutes = strtotime( '+30 minutes' );
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> function tearDown() {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -306,4 +318,168 @@
</span><span class="cx" style="display: block; padding: 0 10px"> // following event should be there too
</span><span class="cx" style="display: block; padding: 0 10px"> $this->assertEquals( $ts2, wp_next_scheduled( $hook, $args ) );
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ /**
+ * Ensure the pre_scheduled_event filter prevents
+ * modification of the cron_array_option.
+ *
+ * @ticket 32656
+ */
+ function test_pre_schedule_event_filter() {
+ $hook = __FUNCTION__;
+ $args = array( 'arg1' );
+ $ts1 = strtotime( '+30 minutes' );
+ $ts2 = strtotime( '+3 minutes' );
+
+ $expected = _get_cron_array();
+
+ add_filter( 'pre_schedule_event', array( $this, '_filter_pre_schedule_event_filter' ), 10, 2 );
+
+ $this->assertTrue( wp_schedule_single_event( $ts1, $hook, $args ) );
+ $this->assertTrue( wp_schedule_event( $ts2, 'hourly', $hook ) );
+
+ // Check cron option is unchanged.
+ $this->assertSame( $expected, _get_cron_array() );
+
+ $expected_preflight[ $ts2 ][ $hook ][ md5( serialize( array() ) ) ] = array(
+ 'schedule' => 'hourly',
+ 'interval' => HOUR_IN_SECONDS,
+ 'args' => array(),
+ );
+
+ $expected_preflight[ $ts1 ][ $hook ][ md5( serialize( $args ) ) ] = array(
+ 'schedule' => false,
+ 'interval' => 0,
+ 'args' => $args,
+ );
+
+ $this->assertSame( $expected_preflight, $this->preflight_cron_array );
+ }
+
+ /**
+ * Filter the scheduling of events to use the preflight array.
+ */
+ function _filter_pre_schedule_event_filter( $null, $event ) {
+ $key = md5( serialize( $event->args ) );
+
+ $this->preflight_cron_array[ $event->timestamp ][ $event->hook ][ $key ] = array(
+ 'schedule' => $event->schedule,
+ 'interval' => isset( $event->interval ) ? $event->interval : 0,
+ 'args' => $event->args,
+ );
+ uksort( $this->preflight_cron_array, 'strnatcasecmp' );
+ return true;
+ }
+
+ /**
+ * Ensure the pre_reschedule_event filter prevents
+ * modification of the cron_array_option.
+ *
+ * @ticket 32656
+ */
+ function test_pre_reschedule_event_filter() {
+ $hook = __FUNCTION__;
+ $ts1 = strtotime( '+30 minutes' );
+
+ // Add an event
+ $this->assertTrue( wp_schedule_event( $ts1, 'hourly', $hook ) );
+ $expected = _get_cron_array();
+
+ // Add preflight filter.
+ add_filter( 'pre_reschedule_event', '__return_true' );
+
+ // Reschedule event with preflight filter in place.
+ wp_reschedule_event( $ts1, 'daily', $hook );
+
+ // Check cron option is unchanged.
+ $this->assertSame( $expected, _get_cron_array() );
+ }
+
+ /**
+ * Ensure the pre_unschedule_event filter prevents
+ * modification of the cron_array_option.
+ *
+ * @ticket 32656
+ */
+ function test_pre_unschedule_event_filter() {
+ $hook = __FUNCTION__;
+ $ts1 = strtotime( '+30 minutes' );
+
+ // Add an event
+ $this->assertTrue( wp_schedule_event( $ts1, 'hourly', $hook ) );
+ $expected = _get_cron_array();
+
+ // Add preflight filter.
+ add_filter( 'pre_unschedule_event', '__return_true' );
+
+ // Unschedule event with preflight filter in place.
+ wp_unschedule_event( $ts1, $hook );
+
+ // Check cron option is unchanged.
+ $this->assertSame( $expected, _get_cron_array() );
+ }
+
+ /**
+ * Ensure the clearing scheduled hooks filter prevents
+ * modification of the cron_array_option.
+ *
+ * @ticket 32656
+ */
+ function test_pre_clear_scheduled_hook_filters() {
+ $hook = __FUNCTION__;
+ $ts1 = strtotime( '+30 minutes' );
+
+ // Add an event
+ $this->assertTrue( wp_schedule_event( $ts1, 'hourly', $hook ) );
+ $expected = _get_cron_array();
+
+ // Add preflight filters.
+ add_filter( 'pre_clear_scheduled_hook', '__return_true' );
+ add_filter( 'pre_unschedule_hook', '__return_zero' );
+
+ // Unschedule event with preflight filter in place.
+ wp_clear_scheduled_hook( $hook );
+
+ // Check cron option is unchanged.
+ $this->assertSame( $expected, _get_cron_array() );
+
+ // Unschedule all events with preflight filter in place.
+ wp_unschedule_hook( $hook );
+
+ // Check cron option is unchanged.
+ $this->assertSame( $expected, _get_cron_array() );
+ }
+
+ /**
+ * Ensure the preflight hooks for scheduled events
+ * return a filtered value as expected.
+ *
+ * @ticket 32656
+ */
+ function test_pre_scheduled_event_hooks() {
+ add_filter( 'pre_get_scheduled_event', array( $this, 'filter_pre_scheduled_event_hooks' ) );
+ add_filter( 'pre_next_scheduled', array( $this, 'filter_pre_scheduled_event_hooks' ) );
+
+ $actual = wp_get_scheduled_event( 'preflight_event', array(), $this->plus_thirty_minutes );
+ $actual2 = wp_next_scheduled( 'preflight_event', array() );
+
+ $expected = (object) array(
+ 'hook' => 'preflight_event',
+ 'timestamp' => $this->plus_thirty_minutes,
+ 'schedule' => false,
+ 'args' => array(),
+ );
+
+ $this->assertEquals( $expected, $actual );
+ $this->assertEquals( $expected, $actual2 );
+ }
+
+ function filter_pre_scheduled_event_hooks() {
+ return (object) array(
+ 'hook' => 'preflight_event',
+ 'timestamp' => $this->plus_thirty_minutes,
+ 'schedule' => false,
+ 'args' => array(),
+ );
+ }
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span></span></pre>
</div>
</div>
</body>
</html>