Changeset 60704 for trunk/src/wp-includes/class-wp-script-modules.php

Timestamp:

09/03/2025 10:15:31 PM (5 months ago)

Author:

westonruter

Message:

Script Loader: Introduce fetchpriority for Scripts and Script Modules.

• Allow scripts and script modules to be registered with a fetchpriority of auto (default), high, low:
  • When registering a script, add a fetchpriority arg to go alongside the strategy arg which was added for loading scripts with the defer and async loading strategies. See #12009.
  • For script modules, introduce an $args array parameter with a fetchpriority key to the wp_register_script_module(), and wp_enqueue_script_module() functions (and their respective underlying WP_Script_Modules::register() and WP_Script_Modules::enqueue() methods). This $args parameter corresponds with the same parameter used when registering non-module scripts.
  • Also for script modules, introduce WP_Script_Modules::set_fetchpriority() to override the fetchpriority for what was previously registered.
  • Emit a _doing_it_wrong() warning when an invalid fetchpriority value is used, and when fetchpriority is added to a script alias.
  • Include fetchpriority as an attribute on printed SCRIPT tags as well as on preload LINK tags for static script module dependencies.
• Use a fetchpriority of low by default for:
  • Script modules used with the Interactivity API. For overriding this default in blocks, see ​Gutenberg#71366.
  • The comment-reply script.
• Improve type checks and type hints.

Developed in ​GitHub PR, with ​companion for Gutenberg.

Props westonruter, jonsurrell, swissspidy, luisherranz, kraftbj, audrasjb, dennysdionigi.
Fixes #61734.

File:

• trunk/src/wp-includes/class-wp-script-modules.php (modified) (8 diffs)

trunk/src/wp-includes/class-wp-script-modules.php

@@ -47 +47 @@
      *
      * @since 6.5.0
+     * @since 6.9.0 Added the $args parameter.
      *
      * @param string            $id       The identifier of the script module. Should be unique. It will be used in the
@@ -72 +73 @@
      *                                    is set to false, the version number is the currently installed WordPress version.
      *                                    If $version is set to null, no version is added.
-     */
-    public function register( string $id, string $src, array $deps = array(), $version = false ) {
+     * @param array             $args     {
+     *     Optional. An array of additional args. Default empty array.
+     *
+     *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
+     * }
+     */
+    public function register( string $id, string $src, array $deps = array(), $version = false, array $args = array() ) {
         if ( ! isset( $this->registered[ $id ] ) ) {
             $dependencies = array();
             foreach ( $deps as $dependency ) {
                 if ( is_array( $dependency ) ) {
-                    if ( ! isset( $dependency['id'] ) ) {
+                    if ( ! isset( $dependency['id'] ) || ! is_string( $dependency['id'] ) ) {
                         _doing_it_wrong( __METHOD__, __( 'Missing required id key in entry among dependencies array.' ), '6.5.0' );
                         continue;
@@ -96 +102 @@
             }
 
+            $fetchpriority = 'auto';
+            if ( isset( $args['fetchpriority'] ) ) {
+                if ( $this->is_valid_fetchpriority( $args['fetchpriority'] ) ) {
+                    $fetchpriority = $args['fetchpriority'];
+                } else {
+                    _doing_it_wrong(
+                        __METHOD__,
+                        sprintf(
+                            /* translators: 1: $fetchpriority, 2: $id */
+                            __( 'Invalid fetchpriority `%1$s` defined for `%2$s` during script registration.' ),
+                            is_string( $args['fetchpriority'] ) ? $args['fetchpriority'] : gettype( $args['fetchpriority'] ),
+                            $id
+                        ),
+                        '6.9.0'
+                    );
+                }
+            }
+
             $this->registered[ $id ] = array(
-                'src'          => $src,
-                'version'      => $version,
-                'enqueue'      => isset( $this->enqueued_before_registered[ $id ] ),
-                'dependencies' => $dependencies,
+                'src'           => $src,
+                'version'       => $version,
+                'enqueue'       => isset( $this->enqueued_before_registered[ $id ] ),
+                'dependencies'  => $dependencies,
+                'fetchpriority' => $fetchpriority,
             );
         }
+    }
+
+    /**
+     * Checks if the provided fetchpriority is valid.
+     *
+     * @since 6.9.0
+     *
+     * @param string|mixed $priority Fetch priority.
+     * @return bool Whether valid fetchpriority.
+     */
+    private function is_valid_fetchpriority( $priority ): bool {
+        return in_array( $priority, array( 'auto', 'low', 'high' ), true );
+    }
+
+    /**
+     * Sets the fetch priority for a script module.
+     *
+     * @since 6.9.0
+     *
+     * @param string              $id       Script module identifier.
+     * @param 'auto'|'low'|'high' $priority Fetch priority for the script module.
+     * @return bool Whether setting the fetchpriority was successful.
+     */
+    public function set_fetchpriority( string $id, string $priority ): bool {
+        if ( ! isset( $this->registered[ $id ] ) ) {
+            return false;
+        }
+
+        if ( '' === $priority ) {
+            $priority = 'auto';
+        }
+
+        if ( ! $this->is_valid_fetchpriority( $priority ) ) {
+            _doing_it_wrong(
+                __METHOD__,
+                /* translators: %s: Invalid fetchpriority. */
+                sprintf( __( 'Invalid fetchpriority: %s' ), $priority ),
+                '6.9.0'
+            );
+            return false;
+        }
+
+        $this->registered[ $id ]['fetchpriority'] = $priority;
+        return true;
     }
 
@@ -112 +181 @@
      *
      * @since 6.5.0
+     * @since 6.9.0 Added the $args parameter.
      *
      * @param string            $id       The identifier of the script module. Should be unique. It will be used in the
@@ -137 +207 @@
      *                                    is set to false, the version number is the currently installed WordPress version.
      *                                    If $version is set to null, no version is added.
-     */
-    public function enqueue( string $id, string $src = '', array $deps = array(), $version = false ) {
+     * @param array             $args     {
+     *     Optional. An array of additional args. Default empty array.
+     *
+     *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
+     * }
+     */
+    public function enqueue( string $id, string $src = '', array $deps = array(), $version = false, array $args = array() ) {
         if ( isset( $this->registered[ $id ] ) ) {
             $this->registered[ $id ]['enqueue'] = true;
         } elseif ( $src ) {
-            $this->register( $id, $src, $deps, $version );
+            $this->register( $id, $src, $deps, $version, $args );
             $this->registered[ $id ]['enqueue'] = true;
         } else {
@@ -209 +284 @@
     public function print_enqueued_script_modules() {
         foreach ( $this->get_marked_for_enqueue() as $id => $script_module ) {
-            wp_print_script_tag(
-                array(
-                    'type' => 'module',
-                    'src'  => $this->get_src( $id ),
-                    'id'   => $id . '-js-module',
-                )
+            $args = array(
+                'type' => 'module',
+                'src'  => $this->get_src( $id ),
+                'id'   => $id . '-js-module',
             );
+            if ( 'auto' !== $script_module['fetchpriority'] ) {
+                $args['fetchpriority'] = $script_module['fetchpriority'];
+            }
+            wp_print_script_tag( $args );
         }
     }
@@ -232 +309 @@
             if ( true !== $script_module['enqueue'] ) {
                 echo sprintf(
-                    '<link rel="modulepreload" href="%s" id="%s">',
+                    '<link rel="modulepreload" href="%s" id="%s"%s>',
                     esc_url( $this->get_src( $id ) ),
-                    esc_attr( $id . '-js-modulepreload' )
+                    esc_attr( $id . '-js-modulepreload' ),
+                    'auto' !== $script_module['fetchpriority'] ? sprintf( ' fetchpriority="%s"', esc_attr( $script_module['fetchpriority'] ) ) : ''
                 );
             }
@@ -279 +357 @@
      * @since 6.5.0
      *
-     * @return array[] Script modules marked for enqueue, keyed by script module identifier.
+     * @return array<string, array> Script modules marked for enqueue, keyed by script module identifier.
      */
     private function get_marked_for_enqueue(): array {