Changeset 59824 for trunk/src/wp-includes/cron.php

Timestamp:

02/14/2025 07:35:51 PM (4 months ago)

Author:

johnbillion

Message:

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 #52655

File:

• trunk/src/wp-includes/cron.php (modified) (6 diffs)

trunk/src/wp-includes/cron.php

@@ -316 +316 @@
  * Reschedules a recurring event.
  *
- * Mainly for internal use, this takes the UTC timestamp of a previously run
+ * Mainly for internal use, this takes the Unix timestamp (UTC) of a previously run
  * recurring event and reschedules it for its next run.
  *
@@ -486 +486 @@
      *
      * @param null|bool|WP_Error $pre       Value to return instead. Default null to continue unscheduling the event.
-     * @param int                $timestamp Timestamp for when to run the event.
+     * @param int                $timestamp Unix timestamp (UTC) 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.
@@ -819 +819 @@
 
 /**
- * Retrieves the next timestamp for an event.
+ * Retrieves the timestamp of the next scheduled event for the given hook.
  *
  * @since 2.1.0
@@ -828 +828 @@
  *                     event, so they should be the same as those used when originally scheduling the event.
  *                     Default empty array.
- * @return int|false The Unix timestamp of the next time the event will occur. False if the event doesn't exist.
+ * @return int|false The Unix timestamp (UTC) of the next time the event will occur. False if the event doesn't exist.
  */
 function wp_next_scheduled( $hook, $args = array() ) {
@@ -837 +837 @@
     }
 
-    return $next_event->timestamp;
+    /**
+     * 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 );
 }
 
@@ -930 +950 @@
      *     }
      * }
-     * @param string $doing_wp_cron The unix timestamp of the cron lock.
+     * @param string $doing_wp_cron The Unix timestamp (UTC) of the cron lock.
      */
     $cron_request = apply_filters(