Changeset 62752 for trunk/src/wp-includes/class-wp-speculation-rules.php

Timestamp:

07/15/2026 07:22:36 AM (7 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.

File:

• trunk/src/wp-includes/class-wp-speculation-rules.php (modified) (2 diffs)

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 ] );
         }