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

Timestamp:

09/03/2025 10:15:31 PM (12 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 {