Changeset 62752 for trunk/src/wp-includes/speculative-loading.php

Timestamp:

07/15/2026 07:22:36 AM (2 months 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/speculative-loading.php (modified) (4 diffs)

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: