Changeset 62752

Timestamp:

07/15/2026 07:22:36 AM (4 weeks ago)

Author:

westonruter

Message:

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 ​https://github.com/WordPress/wordpress-develop/pull/12514.
Follow-up to r59837.

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

Location:

trunk

Files:

• src/wp-includes/class-wp-speculation-rules.php (modified) (2 diffs)
• src/wp-includes/speculative-loading.php (modified) (4 diffs)
• tests/phpunit/tests/speculative-loading/wpGetSpeculationRules.php (modified) (3 diffs)
• tests/phpunit/tests/speculative-loading/wpGetSpeculationRulesConfiguration.php (modified) (2 diffs)
• tests/phpunit/tests/speculative-loading/wpGetSpeculationRulesDefaultConfiguration.php (added)

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

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

trunk/src/wp-includes/speculative-loading.php

@@ -12 +12 @@
  *
  * @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 {
@@ -60 +68 @@
 
         // 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(
@@ -89 +99 @@
                 'eagerness' => $config['eagerness'],
         );
+}
+
+/**
+ * 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;
 }
 
@@ -153 +240 @@
          */
         $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:

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

@@ -22 +22 @@
         );
 
-        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(
@@ -40 +51 @@
 
                 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();
         }
 
@@ -559 +582 @@
                 $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'] );
+        }
 }

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

@@ -13 +13 @@
 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();
         }
 
@@ -265 +288 @@
                 );
         }
+
+        /**
+         * 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() );
+        }
 }