Cron API: Spawn cron jobs on shutdown hook.

Modifies `wp_cron()` to register the spawning of cron jobs on the `shutdown` hook rather than the `wp_loaded` hook.

The loopback request made while spawning cron jobs is intended to be non-blocking, however in some circumstances that isn't the case and the spawning will increase the time to first byte.

Props westonruter, pmbaldha, mukesh27.
Fixes #63858.


git-svn-id: https://develop.svn.wordpress.org/trunk@60925 602fd350-edb4-49c9-b593-d223f7449a82

Author: peterwilsoncc

src/wp-includes/cron.php

@@ -972,30 +972,26 @@ function spawn_cron( $gmt_time = 0 ) {
 }
 
 /**
- * Registers _wp_cron() to run on the {@see 'wp_loaded'} action.
+ * Registers _wp_cron() to run on the {@see 'shutdown'} action.
  *
- * If the {@see 'wp_loaded'} action has already fired, this function calls
- * _wp_cron() directly.
- *
- * Warning: This function may return Boolean FALSE, but may also return a non-Boolean
- * value which evaluates to FALSE. For information about casting to booleans see the
- * {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use
- * the `===` operator for testing the return value of this function.
+ * The spawn_cron() function attempts to make a non-blocking loopback request to `wp-cron.php` (when alternative
+ * cron is not being used). However, the wp_remote_post() function does not always respect the `timeout` and
+ * `blocking` parameters. A timeout of `0.01` may end up taking 1 second. When this runs at the {@see 'wp_loaded'}
+ * action, it increases the Time To First Byte (TTFB) since the HTML cannot be sent while waiting for the cron request
+ * to initiate. Moving the spawning of cron to the {@see 'shutdown'} hook allows for the server to flush the HTML document to
+ * the browser while waiting for the request.
  *
  * @since 2.1.0
  * @since 5.1.0 Return value added to indicate success or failure.
  * @since 5.7.0 Functionality moved to _wp_cron() to which this becomes a wrapper.
- *
- * @return false|int|void On success an integer indicating number of events spawned (0 indicates no
- *                        events needed to be spawned), false if spawning fails for one or more events or
- *                        void if the function registered _wp_cron() to run on the action.
+ * @since 6.9.0 The _wp_cron() callback is moved from {@see 'wp_loaded'} to the {@see 'shutdown'} action; the function always returns void.
  */
-function wp_cron() {
-	if ( did_action( 'wp_loaded' ) ) {
-		return _wp_cron();
+function wp_cron(): void {
+	if ( doing_action( 'shutdown' ) ) {
+		_wp_cron();
+	} else {
+		add_action( 'shutdown', '_wp_cron' );
 	}
-
-	add_action( 'wp_loaded', '_wp_cron', 20 );
 }
 
 /**

tests/phpunit/tests/cron.php

@@ -1330,4 +1330,27 @@ static function () {
 		$this->assertWPError( $unscheduled );
 		$this->assertSame( 'could_not_set', $unscheduled->get_error_code() );
 	}
+
+	/**
+	 * @ticket 63858
+	 *
+	 * @covers ::wp_cron
+	 */
+	public function test_wp_cron_before_shutdown() {
+		remove_all_actions( 'shutdown' );
+		wp_cron();
+		$this->assertSame( 10, has_action( 'shutdown', '_wp_cron' ), 'Expected _wp_cron() to be scheduled for shutdown.' );
+	}
+
+	/**
+	 * @ticket 63858
+	 *
+	 * @covers ::wp_cron
+	 */
+	public function test_wp_cron_already_at_shutdown() {
+		remove_all_actions( 'shutdown' );
+		add_action( 'shutdown', 'wp_cron' );
+		do_action( 'shutdown' );
+		$this->assertFalse( has_action( 'shutdown', '_wp_cron' ), 'Expected wp_cron() to not add _wp_cron() to run at shutdown.' );
+	}
 }