<!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>[59824] trunk/src/wp-includes/cron.php: Cron API: Introduce the `wp_next_scheduled` filter which allows overriding the timestamp for the next scheduled event for the given hook.</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/59824">59824</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/59824","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>johnbillion</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2025-02-14 19:35:51 +0000 (Fri, 14 Feb 2025)</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 API: Introduce the `wp_next_scheduled` filter which allows overriding the timestamp for the next scheduled event for the given hook.
This change also standardises some descriptions of the timestamp field used in various functions.
Props infosatech, peterwilsoncc
Fixes <a href="https://core.trac.wordpress.org/ticket/52655">#52655</a></pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludescronphp">trunk/src/wp-includes/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 2025-02-14 18:36:48 UTC (rev 59823)
+++ trunk/src/wp-includes/cron.php 2025-02-14 19:35:51 UTC (rev 59824)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -315,7 +315,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> /**
</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><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * Mainly for internal use, this takes the UTC timestamp of a previously run
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Mainly for internal use, this takes the Unix timestamp (UTC) of a previously run
</ins><span class="cx" style="display: block; padding: 0 10px"> * recurring event and reschedules it for its next run.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * To change upcoming scheduled events, use wp_schedule_event() to
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -485,7 +485,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param null|bool|WP_Error $pre Value to return instead. Default null to continue unscheduling the event.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param int $timestamp Timestamp for when to run the event.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param int $timestamp Unix timestamp (UTC) for when to run the event.
</ins><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 Arguments to pass to the hook's callback function.
</span><span class="cx" style="display: block; padding: 0 10px"> * @param bool $wp_error Whether to return a WP_Error on failure.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -818,7 +818,7 @@
</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><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * Retrieves the next timestamp for an event.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Retrieves the timestamp of the next scheduled event for the given hook.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 2.1.0
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -827,7 +827,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * Although not passed to a callback, these arguments are used to uniquely identify the
</span><span class="cx" style="display: block; padding: 0 10px"> * event, so they should be the same as those used when originally scheduling the event.
</span><span class="cx" style="display: block; padding: 0 10px"> * Default empty array.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @return int|false The Unix timestamp of the next time the event will occur. False if the event doesn't exist.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @return int|false The Unix timestamp (UTC) of the next time the event will occur. False if the event doesn't exist.
</ins><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><span class="cx" style="display: block; padding: 0 10px"> $next_event = wp_get_scheduled_event( $hook, $args );
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -836,7 +836,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><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- return $next_event->timestamp;
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Filters the timestamp of the next scheduled event for the given hook.
+ *
+ * @since 6.8.0
+ *
+ * @param int $timestamp Unix timestamp (UTC) for when to next run the event.
+ * @param object $next_event {
+ * An object containing an event's data.
+ *
+ * @type string $hook Action hook of the event.
+ * @type int $timestamp Unix timestamp (UTC) for when to next run the event.
+ * @type string $schedule How often the event should subsequently recur.
+ * @type array $args Array containing each separate argument to pass to the hook
+ * callback function.
+ * @type int $interval Optional. The interval time in seconds for the schedule. Only
+ * present for recurring events.
+ * }
+ * @param array $args Array containing each separate argument to pass to the hook
+ * callback function.
+ */
+ return apply_filters( 'wp_next_scheduled', $next_event->timestamp, $next_event, $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">@@ -929,7 +949,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * @type bool $sslverify Whether SSL should be verified for the request. Default 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">- * @param string $doing_wp_cron The unix timestamp of the cron lock.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param string $doing_wp_cron The Unix timestamp (UTC) of the cron lock.
</ins><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> $cron_request = apply_filters(
</span><span class="cx" style="display: block; padding: 0 10px"> 'cron_request',
</span></span></pre>
</div>
</div>
</body>
</html>