General: Allow configuration of speculative loading defaults via env variables and constants.

Introduce two overrides that let a site or hosting provider change the default speculative loading configuration that the `auto` value resolves to, without having to ship an mu-plugin:

* `WP_SPECULATIVE_LOADING_DEFAULT_MODE` (`prefetch` or `prerender`)
* `WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS` (`conservative`, `moderate`, or `eager`).

Each may be supplied as an environment variable, read via `getenv()`, or as a constant of the same name that takes precedence over it, mirroring how `wp_get_environment_type()` resolves `WP_ENVIRONMENT_TYPE`. An unrecognized value falls back to the core default.

These overrides only change what `auto` resolves to, so an explicit mode or eagerness supplied through the `wp_speculation_rules_configuration` filter still wins. An `eagerness` of `immediate` is rejected because WordPress does not permit it for the document-level rules it generates; accepting it would cause `WP_Speculation_Rules::add_rule()` to reject the rule and leave the page with no speculation rules at all.

Also relax `WP_Speculation_Rules::is_valid_mode()` and `WP_Speculation_Rules::is_valid_eagerness()` to accept `mixed`, so an arbitrary value from the filter is validated and rejected rather than raising a `TypeError`.

Fix PHPStan errors in speculative loading functions resulting from insufficient typing.

Developed in WordPress#12514.
Follow-up to r59837.

Props westonruter, mukesh27, adamsilverstein, swissspidy.
See #64066, #62503, #64896, #64898.
Fixes #65624.


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

Author: westonruter

src/wp-includes/class-wp-speculation-rules.php

@@ -259,24 +259,30 @@ private function is_valid_id( string $id ): bool {
 	 * Checks whether the given speculation rules mode is valid.
 	 *
 	 * @since 6.8.0
+	 * @since 7.1.0 The $mode param now allows mixed and not just string.
 	 *
-	 * @param string $mode Speculation rules mode.
+	 * @param mixed $mode Speculation rules mode.
 	 * @return bool True if valid, false otherwise.
+	 *
+	 * @phpstan-assert-if-true 'prefetch'|'prerender' $mode
 	 */
-	public static function is_valid_mode( string $mode ): bool {
-		return isset( self::$mode_allowlist[ $mode ] );
+	public static function is_valid_mode( $mode ): bool {
+		return is_string( $mode ) && isset( self::$mode_allowlist[ $mode ] );
 	}
 
 	/**
 	 * Checks whether the given speculation rules eagerness is valid.
 	 *
 	 * @since 6.8.0
+	 * @since 7.1.0 The $eagerness param now allows mixed and not just string.
 	 *
-	 * @param string $eagerness Speculation rules eagerness.
+	 * @param mixed $eagerness Speculation rules eagerness.
 	 * @return bool True if valid, false otherwise.
+	 *
+	 * @phpstan-assert-if-true 'conservative'|'moderate'|'eager'|'immediate' $eagerness
 	 */
-	public static function is_valid_eagerness( string $eagerness ): bool {
-		return isset( self::$eagerness_allowlist[ $eagerness ] );
+	public static function is_valid_eagerness( $eagerness ): bool {
+		return is_string( $eagerness ) && isset( self::$eagerness_allowlist[ $eagerness ] );
 	}
 
 	/**

src/wp-includes/speculative-loading.php

@@ -11,9 +11,17 @@
  * Returns the speculation rules configuration.
  *
  * @since 6.8.0
+ * @since 7.1.0 The `WP_SPECULATIVE_LOADING_DEFAULT_MODE` and `WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS` constants and
+ *              environment variables can now specify the default mode and eagerness, respectively.
+ *
+ * @see wp_get_speculation_rules_default_configuration()
  *
  * @return array<string, string>|null Associative array with 'mode' and 'eagerness' keys, or null if speculative
  *                                    loading is disabled.
+ * @phpstan-return array{
+ *     mode: 'prefetch'|'prerender',
+ *     eagerness: 'conservative'|'moderate'|'eager',
+ * }|null
  */
 function wp_get_speculation_rules_configuration(): ?array {
 	// By default, speculative loading is only enabled for sites with pretty permalinks when no user is logged in.
@@ -59,8 +67,10 @@ function wp_get_speculation_rules_configuration(): ?array {
 	}
 
 	// Sanitize the configuration and replace 'auto' with current defaults.
-	$default_mode      = 'prefetch';
-	$default_eagerness = 'conservative';
+	$defaults          = wp_get_speculation_rules_default_configuration();
+	$default_mode      = $defaults['mode'];
+	$default_eagerness = $defaults['eagerness'];
+
 	if ( ! is_array( $config ) ) {
 		return array(
 			'mode'      => $default_mode,
@@ -90,6 +100,83 @@ function wp_get_speculation_rules_configuration(): ?array {
 	);
 }
 
+/**
+ * Returns the default speculation rules configuration that the value 'auto' resolves to.
+ *
+ * WordPress Core defaults to a mode of 'prefetch' and an eagerness of 'conservative'. Hosting providers can override
+ * either default by way of the `WP_SPECULATIVE_LOADING_DEFAULT_MODE` and `WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS`
+ * constants or environment variables. This only changes what the 'auto' value resolves to, so a plugin which supplies
+ * an explicit mode or eagerness via the {@see 'wp_speculation_rules_configuration'} filter continues to take
+ * precedence.
+ *
+ * Note that an eagerness of 'immediate' is not permitted as a default, since WordPress does not allow it for the
+ * document-level rules that it generates.
+ *
+ * @since 7.1.0
+ * @access private
+ *
+ * @return array<string, string> Associative array with 'mode' and 'eagerness' keys.
+ * @phpstan-return array{
+ *     mode: 'prefetch'|'prerender',
+ *     eagerness: 'conservative'|'moderate'|'eager',
+ * }
+ */
+function wp_get_speculation_rules_default_configuration(): array {
+	$default_mode = 'prefetch';
+	$mode         = wp_get_speculative_loading_override( 'WP_SPECULATIVE_LOADING_DEFAULT_MODE' );
+	if ( WP_Speculation_Rules::is_valid_mode( $mode ) ) {
+		$default_mode = $mode;
+	}
+
+	$default_eagerness = 'conservative';
+	$eagerness         = wp_get_speculative_loading_override( 'WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS' );
+	if (
+		WP_Speculation_Rules::is_valid_eagerness( $eagerness ) &&
+		// 'immediate' is a valid eagerness, but for safety WordPress does not allow it for document-level rules.
+		'immediate' !== $eagerness
+	) {
+		$default_eagerness = $eagerness;
+	}
+
+	return array(
+		'mode'      => $default_mode,
+		'eagerness' => $default_eagerness,
+	);
+}
+
+/**
+ * Returns the value of a speculative loading override, as supplied by a constant or an environment variable.
+ *
+ * The constant takes precedence over the environment variable, consistent with {@see wp_get_environment_type()}.
+ *
+ * @since 7.1.0
+ * @access private
+ *
+ * @param string $name Name of the constant and environment variable to look up.
+ * @return string|null The override value, or null if neither is set.
+ */
+function wp_get_speculative_loading_override( string $name ): ?string {
+	$value = null;
+
+	// Check if the environment variable has been set, if `getenv` is available on the system.
+	if ( function_exists( 'getenv' ) ) {
+		$has_env = getenv( $name );
+		if ( false !== $has_env ) {
+			$value = $has_env;
+		}
+	}
+
+	// Fetch the value from a constant, which overrides the environment variable.
+	if ( defined( $name ) ) {
+		$has_constant = constant( $name );
+		if ( is_string( $has_constant ) ) {
+			$value = $has_constant;
+		}
+	}
+
+	return $value;
+}
+
 /**
  * Returns the full speculation rules data based on the configuration.
  *
@@ -152,6 +239,7 @@ function wp_get_speculation_rules(): ?WP_Speculation_Rules {
 	 * @param string   $mode               Mode used to apply speculative loading. Either 'prefetch' or 'prerender'.
 	 */
 	$href_exclude_paths = (array) apply_filters( 'wp_speculation_rules_href_exclude_paths', array(), $mode );
+	$href_exclude_paths = array_filter( $href_exclude_paths, 'is_string' );
 
 	// Ensure that:
 	// 1. There are no duplicates.

tests/phpunit/tests/speculative-loading/wpGetSpeculationRules.php

@@ -21,9 +21,20 @@ class Tests_Speculative_Loading_wpGetSpeculationRules extends WP_UnitTestCase {
 		'eagerness' => 'conservative',
 	);
 
-	public function set_up() {
+	/**
+	 * Stores the original speculative loading env values for cleanup.
+	 *
+	 * @var array<string, string|false>
+	 */
+	private array $original_env = array();
+
+	public function set_up(): void {
 		parent::set_up();
 
+		foreach ( array( 'WP_SPECULATIVE_LOADING_DEFAULT_MODE', 'WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS' ) as $name ) {
+			$this->original_env[ $name ] = getenv( $name );
+		}
+
 		add_filter(
 			'template_directory_uri',
 			static function () {
@@ -41,6 +52,18 @@ static function () {
 		update_option( 'permalink_structure', '/%year%/%monthnum%/%day%/%postname%/' );
 	}
 
+	public function tear_down(): void {
+		foreach ( $this->original_env as $name => $value ) {
+			if ( false === $value ) {
+				putenv( $name );
+			} else {
+				putenv( "{$name}={$value}" );
+			}
+		}
+
+		parent::tear_down();
+	}
+
 	/**
 	 * Tests speculation rules output with prefetch for the different eagerness levels.
 	 *
@@ -558,4 +581,43 @@ function () {
 		$this->assertSame( 'moderate', $rules['prerender'][0]['eagerness'] );
 		$this->assertSame( 'eager', $rules['prerender'][1]['eagerness'] );
 	}
+
+	/**
+	 * Tests that an overridden default eagerness is applied to the main document-level rule.
+	 *
+	 * @ticket 65624
+	 */
+	public function test_wp_get_speculation_rules_with_overridden_default_eagerness(): void {
+		putenv( 'WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS=moderate' );
+
+		$rules = wp_get_speculation_rules();
+		$this->assertInstanceOf( WP_Speculation_Rules::class, $rules );
+
+		$rules = $rules->jsonSerialize();
+
+		$this->assertArrayHasKey( 'prefetch', $rules );
+		$this->assertCount( 1, $rules['prefetch'] );
+		$this->assertSame( 'moderate', $rules['prefetch'][0]['eagerness'] );
+	}
+
+	/**
+	 * Tests that an eagerness of 'immediate' cannot be forced as the default.
+	 *
+	 * WordPress does not allow 'immediate' for the document-level rules it generates, so allowing it as a default
+	 * would cause the main rule to be rejected, leaving no speculation rules at all.
+	 *
+	 * @ticket 65624
+	 */
+	public function test_wp_get_speculation_rules_with_immediate_default_eagerness(): void {
+		putenv( 'WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS=immediate' );
+
+		$rules = wp_get_speculation_rules();
+		$this->assertInstanceOf( WP_Speculation_Rules::class, $rules );
+
+		$rules = $rules->jsonSerialize();
+
+		$this->assertArrayHasKey( 'prefetch', $rules );
+		$this->assertCount( 1, $rules['prefetch'] );
+		$this->assertSame( 'conservative', $rules['prefetch'][0]['eagerness'] );
+	}
 }

tests/phpunit/tests/speculative-loading/wpGetSpeculationRulesConfiguration.php

@@ -12,12 +12,35 @@
  */
 class Tests_Speculative_Loading_wpGetSpeculationRulesConfiguration extends WP_UnitTestCase {
 
-	public function set_up() {
+	/**
+	 * Stores the original speculative loading env values for cleanup.
+	 *
+	 * @var array<string, string|false>
+	 */
+	private array $original_env = array();
+
+	public function set_up(): void {
 		parent::set_up();
 
+		foreach ( array( 'WP_SPECULATIVE_LOADING_DEFAULT_MODE', 'WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS' ) as $name ) {
+			$this->original_env[ $name ] = getenv( $name );
+		}
+
 		update_option( 'permalink_structure', '/%year%/%monthnum%/%day%/%postname%/' );
 	}
 
+	public function tear_down(): void {
+		foreach ( $this->original_env as $name => $value ) {
+			if ( false === $value ) {
+				putenv( $name );
+			} else {
+				putenv( "{$name}={$value}" );
+			}
+		}
+
+		parent::tear_down();
+	}
+
 	/**
 	 * Tests that the default configuration is the expected value.
 	 *
@@ -264,4 +287,63 @@ public static function data_wp_get_speculation_rules_configuration_filter(): arr
 			),
 		);
 	}
+
+	/**
+	 * Tests that an overridden default is what the 'auto' value resolves to.
+	 *
+	 * @ticket 65624
+	 */
+	public function test_wp_get_speculation_rules_configuration_with_overridden_default(): void {
+		putenv( 'WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS=moderate' );
+
+		$this->assertSame(
+			array(
+				'mode'      => 'prefetch',
+				'eagerness' => 'moderate',
+			),
+			wp_get_speculation_rules_configuration()
+		);
+	}
+
+	/**
+	 * Tests that an explicit eagerness from the filter takes precedence over an overridden default.
+	 *
+	 * This ensures a plugin such as Speculative Loading continues to win over a hosting provider's default.
+	 *
+	 * @ticket 65624
+	 */
+	public function test_wp_get_speculation_rules_configuration_filter_beats_overridden_default(): void {
+		putenv( 'WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS=moderate' );
+
+		add_filter(
+			'wp_speculation_rules_configuration',
+			static function () {
+				return array(
+					'mode'      => 'auto',
+					'eagerness' => 'conservative',
+				);
+			}
+		);
+
+		$this->assertSame(
+			array(
+				'mode'      => 'prefetch',
+				'eagerness' => 'conservative',
+			),
+			wp_get_speculation_rules_configuration()
+		);
+	}
+
+	/**
+	 * Tests that speculative loading remains disabled when a default is overridden.
+	 *
+	 * @ticket 65624
+	 */
+	public function test_wp_get_speculation_rules_configuration_with_overridden_default_while_disabled(): void {
+		putenv( 'WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS=moderate' );
+
+		add_filter( 'wp_speculation_rules_configuration', '__return_null' );
+
+		$this->assertNull( wp_get_speculation_rules_configuration() );
+	}
 }