WordPress.org
Get WordPress

Make WordPress Core

Changeset 61587


Ignore:
Timestamp:
02/04/2026 01:41:25 AM (2 months ago)
Author:
westonruter
Message:

Script Loader: Allow classic scripts to depend on script modules.

This allows classic scripts to declare dependencies on script modules by passing module_dependencies in the $args param for wp_register_script() or wp_enqueue_script(). The WP_Script_Modules::get_import_map() method is updated to traverse the dependency tree of all enqueued classic scripts to find any associated script module dependencies and include them in the importmap, enabling dynamic imports of modules within classic scripts.

A _wp_scripts_add_args_data() helper function is introduced to consolidate argument validation and processing for wp_register_script() and wp_enqueue_script(), reducing code duplication. This function validates that the $args array only contains recognized keys (strategy, in_footer, fetchpriority, module_dependencies) and triggers a _doing_it_wrong() notice for any unrecognized keys. Similarly, WP_Scripts::add_data() is updated to do early type checking for the data passed to $args. The script modules in module_dependencies may be referenced by a module ID string or by an array that has an id key, following the same pattern as dependencies in WP_Script_Modules.

When a script module is added to the module_dependencies for a classic script, but it does not exist at the time the importmap is printed, a _doing_it_wrong() notice is emitted.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/8024

Follow-up to [61323].

Props sirreal, westonruter.
See #64229.
Fixes #61500.

Location:
trunk
Files:
6 edited

Legend:

Unmodified
Added
Removed

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

    r61542 r61587  
    8989     * @since 6.9.0 Added the $args parameter.
    9090     *
    91      * @param string                     $id       The identifier of the script module. Should be unique. It will be used in the
    92      *                                             final import map.
    93      * @param string                     $src      Optional. Full URL of the script module, or path of the script module relative
    94      *                                             to the WordPress root directory. If it is provided and the script module has
    95      *                                             not been registered yet, it will be registered.
    96      * @param array<string|array>        $deps     {
    97      *                                                 Optional. List of dependencies.
    98      *
    99      *                                                 @type string|array ...$0 {
    100      *                                                     An array of script module identifiers of the dependencies of this script
    101      *                                                     module. The dependencies can be strings or arrays. If they are arrays,
    102      *                                                     they need an `id` key with the script module identifier, and can contain
    103      *                                                     an `import` key with either `static` or `dynamic`. By default,
    104      *                                                     dependencies that don't contain an `import` key are considered static.
    105      *
    106      *                                                     @type string $id     The script module identifier.
    107      *                                                     @type string $import Optional. Import type. May be either `static` or
    108      *                                                                          `dynamic`. Defaults to `static`.
    109      *                                                 }
    110      *                                             }
    111      * @param string|false|null          $version Optional. String specifying the script module version number. Defaults to false.
    112      *                                             It is added to the URL as a query string for cache busting purposes. If $version
    113      *                                             is set to false, the version number is the currently installed WordPress version.
    114      *                                             If $version is set to null, no version is added.
    115      * @param array<string, string|bool> $args     {
     91     * @param string                              $id      The identifier of the script module. Should be unique. It will be used in the
     92     *                                                     final import map.
     93     * @param string                              $src     Optional. Full URL of the script module, or path of the script module relative
     94     *                                                     to the WordPress root directory. If it is provided and the script module has
     95     *                                                     not been registered yet, it will be registered.
     96     * @param array<string|array<string, string>> $deps    {
     97     *                                                         Optional. List of dependencies.
     98     *
     99     *                                                         @type string|array<string, string> ...$0 {
     100     *                                                             An array of script module identifiers of the dependencies of this script
     101     *                                                             module. The dependencies can be strings or arrays. If they are arrays,
     102     *                                                             they need an `id` key with the script module identifier, and can contain
     103     *                                                             an `import` key with either `static` or `dynamic`. By default,
     104     *                                                             dependencies that don't contain an `import` key are considered static.
     105     *
     106     *                                                             @type string $id     The script module identifier.
     107     *                                                             @type string $import Optional. Import type. May be either `static` or
     108     *                                                                                  `dynamic`. Defaults to `static`.
     109     *                                                         }
     110     *                                                     }
     111     * @param string|false|null                   $version Optional. String specifying the script module version number. Defaults to false.
     112     *                                                     It is added to the URL as a query string for cache busting purposes. If $version
     113     *                                                     is set to false, the version number is the currently installed WordPress version.
     114     *                                                     If $version is set to null, no version is added.
     115     * @param array<string, string|bool>          $args    {
    116116     *     Optional. An array of additional args. Default empty array.
    117117     *
    … …  
    261261     * @since 6.9.0 Added the $args parameter.
    262262     *
    263      * @param string                     $id       The identifier of the script module. Should be unique. It will be used in the
    264      *                                             final import map.
    265      * @param string                     $src      Optional. Full URL of the script module, or path of the script module relative
    266      *                                             to the WordPress root directory. If it is provided and the script module has
    267      *                                             not been registered yet, it will be registered.
    268      * @param array<string|array>        $deps     {
    269      *                                                 Optional. List of dependencies.
    270      *
    271      *                                                 @type string|array ...$0 {
    272      *                                                     An array of script module identifiers of the dependencies of this script
    273      *                                                     module. The dependencies can be strings or arrays. If they are arrays,
    274      *                                                     they need an `id` key with the script module identifier, and can contain
    275      *                                                     an `import` key with either `static` or `dynamic`. By default,
    276      *                                                     dependencies that don't contain an `import` key are considered static.
    277      *
    278      *                                                     @type string $id     The script module identifier.
    279      *                                                     @type string $import Optional. Import type. May be either `static` or
    280      *                                                                          `dynamic`. Defaults to `static`.
    281      *                                                 }
    282      *                                             }
    283      * @param string|false|null          $version Optional. String specifying the script module version number. Defaults to false.
    284      *                                             It is added to the URL as a query string for cache busting purposes. If $version
    285      *                                             is set to false, the version number is the currently installed WordPress version.
    286      *                                             If $version is set to null, no version is added.
    287      * @param array<string, string|bool> $args     {
     263     * @param string                              $id      The identifier of the script module. Should be unique. It will be used in the
     264     *                                                     final import map.
     265     * @param string                              $src     Optional. Full URL of the script module, or path of the script module relative
     266     *                                                     to the WordPress root directory. If it is provided and the script module has
     267     *                                                     not been registered yet, it will be registered.
     268     * @param array<string|array<string, string>> $deps    {
     269     *                                                         Optional. List of dependencies.
     270     *
     271     *                                                         @type string|array<string, string> ...$0 {
     272     *                                                             An array of script module identifiers of the dependencies of this script
     273     *                                                             module. The dependencies can be strings or arrays. If they are arrays,
     274     *                                                             they need an `id` key with the script module identifier, and can contain
     275     *                                                             an `import` key with either `static` or `dynamic`. By default,
     276     *                                                             dependencies that don't contain an `import` key are considered static.
     277     *
     278     *                                                             @type string $id     The script module identifier.
     279     *                                                             @type string $import Optional. Import type. May be either `static` or
     280     *                                                                                  `dynamic`. Defaults to `static`.
     281     *                                                         }
     282     *                                                     }
     283     * @param string|false|null                   $version Optional. String specifying the script module version number. Defaults to false.
     284     *                                                     It is added to the URL as a query string for cache busting purposes. If $version
     285     *                                                     is set to false, the version number is the currently installed WordPress version.
     286     *                                                     If $version is set to null, no version is added.
     287     * @param array<string, string|bool>          $args    {
    288288     *     Optional. An array of additional args. Default empty array.
    289289     *
    … …  
    534534     *
    535535     * @since 6.5.0
     536     * @since 7.0.0 Script module dependencies ('module_dependencies') of classic scripts are now included.
     537     *
     538     * @global WP_Scripts $wp_scripts
    536539     *
    537540     * @return array<string, array<string, string>> Array with an `imports` key mapping to an array of script module
    … …  
    539542     */
    540543    private function get_import_map(): array {
     544        global $wp_scripts;
     545
    541546        $imports = array();
    542         foreach ( array_keys( $this->get_dependencies( $this->queue ) ) as $id ) {
     547
     548        // Identify script modules that are dependencies of classic scripts.
     549        $classic_script_module_dependencies = array();
     550        if ( $wp_scripts instanceof WP_Scripts ) {
     551            $handles = array_merge(
     552                $wp_scripts->queue,
     553                $wp_scripts->to_do,
     554                $wp_scripts->done
     555            );
     556
     557            $processed = array();
     558            while ( ! empty( $handles ) ) {
     559                $handle = array_pop( $handles );
     560                if ( isset( $processed[ $handle ] ) || ! isset( $wp_scripts->registered[ $handle ] ) ) {
     561                    continue;
     562                }
     563                $processed[ $handle ] = true;
     564
     565                $module_dependencies = $wp_scripts->get_data( $handle, 'module_dependencies' );
     566                if ( is_array( $module_dependencies ) ) {
     567                    $missing_module_dependencies = array();
     568                    foreach ( $module_dependencies as $module ) {
     569                        if ( is_string( $module ) ) {
     570                            $id = $module;
     571                        } elseif ( is_array( $module ) && isset( $module['id'] ) && is_string( $module['id'] ) ) {
     572                            $id = $module['id'];
     573                        } else {
     574                            // Invalid module dependency was supplied by direct manipulation of the extra data.
     575                            // Normally, this error scenario would be caught when WP_Scripts::add_data() is called.
     576                            continue;
     577                        }
     578
     579                        if ( ! isset( $this->registered[ $id ] ) ) {
     580                            $missing_module_dependencies[] = $id;
     581                        } else {
     582                            $classic_script_module_dependencies[] = $id;
     583                        }
     584                    }
     585
     586                    if ( count( $missing_module_dependencies ) > 0 ) {
     587                        _doing_it_wrong(
     588                            'WP_Scripts::add_data',
     589                            sprintf(
     590                                /* translators: 1: Script handle, 2: 'module_dependencies', 3: List of missing dependency IDs. */
     591                                __( 'The script with the handle "%1$s" was enqueued with script module dependencies ("%2$s") that are not registered: %3$s.' ),
     592                                $handle,
     593                                'module_dependencies',
     594                                implode( wp_get_list_item_separator(), $missing_module_dependencies )
     595                            ),
     596                            '7.0.0'
     597                        );
     598                    }
     599                }
     600
     601                foreach ( $wp_scripts->registered[ $handle ]->deps as $dep ) {
     602                    if ( ! isset( $processed[ $dep ] ) ) {
     603                        $handles[] = $dep;
     604                    }
     605                }
     606            }
     607        }
     608
     609        // Note: the script modules in $this->queue are not included in the importmap because they get printed as scripts.
     610        $ids = array_unique(
     611            array_merge(
     612                $classic_script_module_dependencies,
     613                array_keys( $this->get_dependencies( array_merge( $this->queue, $classic_script_module_dependencies ) ) )
     614            )
     615        );
     616        foreach ( $ids as $id ) {
    543617            $src = $this->get_src( $id );
    544618            if ( '' !== $src ) {

  • trunk/src/wp-includes/class-wp-scripts.php

    r61542 r61587  
    921921                return false;
    922922            }
     923        } elseif ( 'module_dependencies' === $key ) {
     924            if ( ! is_array( $value ) ) {
     925                _doing_it_wrong(
     926                    __METHOD__,
     927                    sprintf(
     928                        /* translators: 1: 'module_dependencies', 2: Script handle. */
     929                        __( 'The value for "%1$s" must be an array for the "%2$s" script.' ),
     930                        'module_dependencies',
     931                        $handle
     932                    ),
     933                    '7.0.0'
     934                );
     935                return false;
     936            }
     937
     938            $sanitized_value = array();
     939            $has_invalid_ids = false;
     940            foreach ( $value as $module ) {
     941                if (
     942                    is_string( $module ) ||
     943                    ( is_array( $module ) && isset( $module['id'] ) && is_string( $module['id'] ) )
     944                ) {
     945                    $sanitized_value[] = $module;
     946                } else {
     947                    $has_invalid_ids = true;
     948                }
     949            }
     950
     951            if ( $has_invalid_ids ) {
     952                _doing_it_wrong(
     953                    __METHOD__,
     954                    sprintf(
     955                        /* translators: 1: Script handle, 2: 'module_dependencies' */
     956                        __( 'The script handle "%1$s" has one or more of its script module dependencies ("%2$s") which are invalid.' ),
     957                        $handle,
     958                        'module_dependencies'
     959                    ),
     960                    '7.0.0'
     961                );
     962            }
     963
     964            $value = $sanitized_value;
    923965        }
    924966        return parent::add_data( $handle, $key, $value );

  • trunk/src/wp-includes/functions.wp-scripts.php

    r61402 r61587  
    6767        '3.3.0'
    6868    );
     69}
     70
     71/**
     72 * Adds the data for the recognized args and warns for unrecognized args.
     73 *
     74 * @ignore
     75 * @since 7.0.0
     76 *
     77 * @param WP_Scripts $wp_scripts WP_Scripts instance.
     78 * @param string     $handle     Script handle.
     79 * @param array      $args       Array of extra args for the script.
     80 */
     81function _wp_scripts_add_args_data( WP_Scripts $wp_scripts, string $handle, array $args ) {
     82    $allowed_keys = array( 'strategy', 'in_footer', 'fetchpriority', 'module_dependencies' );
     83    $unknown_keys = array_diff( array_keys( $args ), $allowed_keys );
     84    if ( ! empty( $unknown_keys ) ) {
     85        $trace         = debug_backtrace( DEBUG_BACKTRACE_IGNORE_ARGS, 2 );
     86        $function_name = ( $trace[1]['class'] ?? '' ) . ( $trace[1]['type'] ?? '' ) . $trace[1]['function'];
     87        _doing_it_wrong(
     88            $function_name,
     89            sprintf(
     90                /* translators: 1: $args, 2: List of unrecognized keys, 3: List of supported keys. */
     91                __( 'Unrecognized key(s) in the %1$s param: %2$s. Supported keys: %3$s' ),
     92                '$args',
     93                implode( wp_get_list_item_separator(), $unknown_keys ),
     94                implode( wp_get_list_item_separator(), $allowed_keys )
     95            ),
     96            '7.0.0'
     97        );
     98    }
     99
     100    if ( ! empty( $args['in_footer'] ) ) {
     101        $wp_scripts->add_data( $handle, 'group', 1 );
     102    }
     103    if ( ! empty( $args['strategy'] ) ) {
     104        $wp_scripts->add_data( $handle, 'strategy', $args['strategy'] );
     105    }
     106    if ( ! empty( $args['fetchpriority'] ) ) {
     107        $wp_scripts->add_data( $handle, 'fetchpriority', $args['fetchpriority'] );
     108    }
     109    if ( ! empty( $args['module_dependencies'] ) ) {
     110        $wp_scripts->add_data( $handle, 'module_dependencies', $args['module_dependencies'] );
     111    }
    69112}
    70113
    … …  
    160203 * @since 6.3.0 The $in_footer parameter of type boolean was overloaded to be an $args parameter of type array.
    161204 * @since 6.9.0 The $fetchpriority parameter of type string was added to the $args parameter of type array.
    162  *
    163  * @param string                          $handle Name of the script. Should be unique.
    164  * @param string|false                    $src    Full URL of the script, or path of the script relative to the WordPress root directory.
    165  *                                                If source is set to false, script is an alias of other scripts it depends on.
    166  * @param string[]                        $deps   Optional. An array of registered script handles this script depends on. Default empty array.
    167  * @param string|bool|null                $ver    Optional. String specifying script version number, if it has one, which is added to the URL
    168  *                                                as a query string for cache busting purposes. If version is set to false, a version
    169  *                                                number is automatically added equal to current installed WordPress version.
    170  *                                                If set to null, no version is added.
    171  * @param array<string, string|bool>|bool $args   {
    172  *     Optional. An array of additional script loading strategies. Default empty array.
     205 * @since 7.0.0 The $module_dependencies parameter of type string[] was added to the $args parameter of type array.
     206 *
     207 * @param string                                                              $handle Name of the script. Should be unique.
     208 * @param string|false                                                        $src    Full URL of the script, or path of the script relative to the WordPress root directory.
     209 *                                                                                    If source is set to false, script is an alias of other scripts it depends on.
     210 * @param string[]                                                            $deps   Optional. An array of registered script handles this script depends on. Default empty array.
     211 * @param string|bool|null                                                    $ver    Optional. String specifying script version number, if it has one, which is added to the URL
     212 *                                                                                    as a query string for cache busting purposes. If version is set to false, a version
     213 *                                                                                    number is automatically added equal to current installed WordPress version.
     214 *                                                                                    If set to null, no version is added.
     215 * @param array<string, string|bool|array<string|array<string, string>>>|bool $args   {
     216 *     Optional. An array of extra args for the script. Default empty array.
    173217 *     Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false.
    174218 *
    175  *     @type string    $strategy      Optional. If provided, may be either 'defer' or 'async'.
    176  *     @type bool      $in_footer     Optional. Whether to print the script in the footer. Default 'false'.
    177  *     @type string    $fetchpriority Optional. The fetch priority for the script. Default 'auto'.
     219 *     @type string                              $strategy            Optional. If provided, may be either 'defer' or 'async'.
     220 *     @type bool                                $in_footer           Optional. Whether to print the script in the footer. Default 'false'.
     221 *     @type string                              $fetchpriority       Optional. The fetch priority for the script. Default 'auto'.
     222 *     @type array<string|array<string, string>> $module_dependencies Optional. IDs for module dependencies loaded via dynamic import. Default empty array.
     223 *                                                                    For the full data format, see the `$deps` param of {@see wp_register_script_module()}.
    178224 * }
    179225 * @return bool Whether the script has been registered. True on success, false on failure.
    … …  
    190236
    191237    $registered = $wp_scripts->add( $handle, $src, $deps, $ver );
    192     if ( ! empty( $args['in_footer'] ) ) {
    193         $wp_scripts->add_data( $handle, 'group', 1 );
    194     }
    195     if ( ! empty( $args['strategy'] ) ) {
    196         $wp_scripts->add_data( $handle, 'strategy', $args['strategy'] );
    197     }
    198     if ( ! empty( $args['fetchpriority'] ) ) {
    199         $wp_scripts->add_data( $handle, 'fetchpriority', $args['fetchpriority'] );
    200     }
     238    _wp_scripts_add_args_data( $wp_scripts, $handle, $args );
     239
    201240    return $registered;
    202241}
    … …  
    346385 * @since 6.3.0 The $in_footer parameter of type boolean was overloaded to be an $args parameter of type array.
    347386 * @since 6.9.0 The $fetchpriority parameter of type string was added to the $args parameter of type array.
    348  *
    349  * @param string                          $handle Name of the script. Should be unique.
    350  * @param string                          $src    Full URL of the script, or path of the script relative to the WordPress root directory.
    351  *                                                Default empty.
    352  * @param string[]                        $deps   Optional. An array of registered script handles this script depends on. Default empty array.
    353  * @param string|bool|null                $ver    Optional. String specifying script version number, if it has one, which is added to the URL
    354  *                                                as a query string for cache busting purposes. If version is set to false, a version
    355  *                                                number is automatically added equal to current installed WordPress version.
    356  *                                                If set to null, no version is added.
    357  * @param array<string, string|bool>|bool $args   {
    358  *     Optional. An array of additional script loading strategies. Default empty array.
     387 * @since 7.0.0 The $module_dependencies parameter of type string[] was added to the $args parameter of type array.
     388 *
     389 * @param string                                                              $handle Name of the script. Should be unique.
     390 * @param string                                                              $src    Full URL of the script, or path of the script relative to the WordPress root directory.
     391 *                                                                                    Default empty.
     392 * @param string[]                                                            $deps   Optional. An array of registered script handles this script depends on. Default empty array.
     393 * @param string|bool|null                                                    $ver    Optional. String specifying script version number, if it has one, which is added to the URL
     394 *                                                                                    as a query string for cache busting purposes. If version is set to false, a version
     395 *                                                                                    number is automatically added equal to current installed WordPress version.
     396 *                                                                                    If set to null, no version is added.
     397 * @param array<string, string|bool|array<string|array<string, string>>>|bool $args {
     398 *     Optional. An array of extra args for the script. Default empty array.
    359399 *     Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false.
    360400 *
    361  *     @type string    $strategy      Optional. If provided, may be either 'defer' or 'async'.
    362  *     @type bool      $in_footer     Optional. Whether to print the script in the footer. Default 'false'.
    363  *     @type string    $fetchpriority Optional. The fetch priority for the script. Default 'auto'.
     401 *     @type string                              $strategy            Optional. If provided, may be either 'defer' or 'async'.
     402 *     @type bool                                $in_footer           Optional. Whether to print the script in the footer. Default 'false'.
     403 *     @type string                              $fetchpriority       Optional. The fetch priority for the script. Default 'auto'.
     404 *     @type array<string|array<string, string>> $module_dependencies Optional. IDs for module dependencies loaded via dynamic import. Default empty array.
     405 *                                                                    For the full data format, see the `$deps` param of {@see wp_register_script_module()}.
    364406 * }
    365407 */
    … …  
    380422            $wp_scripts->add( $_handle[0], $src, $deps, $ver );
    381423        }
    382         if ( ! empty( $args['in_footer'] ) ) {
    383             $wp_scripts->add_data( $_handle[0], 'group', 1 );
    384         }
    385         if ( ! empty( $args['strategy'] ) ) {
    386             $wp_scripts->add_data( $_handle[0], 'strategy', $args['strategy'] );
    387         }
    388         if ( ! empty( $args['fetchpriority'] ) ) {
    389             $wp_scripts->add_data( $_handle[0], 'fetchpriority', $args['fetchpriority'] );
     424        if ( ! empty( $args ) ) {
     425            _wp_scripts_add_args_data( $wp_scripts, $_handle[0], $args );
    390426        }
    391427    }

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

    r61492 r61587  
    3838 * @since 6.9.0 Added the $args parameter.
    3939 *
    40  * @param string                     $id      The identifier of the script module. Should be unique. It will be used in the
    41  *                                            final import map.
    42  * @param string                     $src     Optional. Full URL of the script module, or path of the script module relative
    43  *                                            to the WordPress root directory. If it is provided and the script module has
    44  *                                            not been registered yet, it will be registered.
    45  * @param array<string|array>        $deps    {
    46  *                                                Optional. List of dependencies.
    47  *
    48  *                                                @type string|array ...$0 {
    49  *                                                    An array of script module identifiers of the dependencies of this script
    50  *                                                    module. The dependencies can be strings or arrays. If they are arrays,
    51  *                                                    they need an `id` key with the script module identifier, and can contain
    52  *                                                    an `import` key with either `static` or `dynamic`. By default,
    53  *                                                    dependencies that don't contain an `import` key are considered static.
    54  *
    55  *                                                    @type string $id     The script module identifier.
    56  *                                                    @type string $import Optional. Import type. May be either `static` or
    57  *                                                                         `dynamic`. Defaults to `static`.
    58  *                                                }
    59  *                                            }
    60  * @param string|false|null          $version Optional. String specifying the script module version number. Defaults to false.
    61  *                                            It is added to the URL as a query string for cache busting purposes. If $version
    62  *                                            is set to false, the version number is the currently installed WordPress version.
    63  *                                            If $version is set to null, no version is added.
    64  * @param array<string, string|bool> $args    {
     40 * @param string                              $id      The identifier of the script module. Should be unique. It will be used in the
     41 *                                                     final import map.
     42 * @param string                              $src     Optional. Full URL of the script module, or path of the script module relative
     43 *                                                     to the WordPress root directory. If it is provided and the script module has
     44 *                                                     not been registered yet, it will be registered.
     45 * @param array<string|array<string, string>> $deps    {
     46 *                                                         Optional. List of dependencies.
     47 *
     48 *                                                         @type string|array<string, string> ...$0 {
     49 *                                                             An array of script module identifiers of the dependencies of this script
     50 *                                                             module. The dependencies can be strings or arrays. If they are arrays,
     51 *                                                             they need an `id` key with the script module identifier, and can contain
     52 *                                                             an `import` key with either `static` or `dynamic`. By default,
     53 *                                                             dependencies that don't contain an `import` key are considered static.
     54 *
     55 *                                                             @type string $id     The script module identifier.
     56 *                                                             @type string $import Optional. Import type. May be either `static` or
     57 *                                                                                  `dynamic`. Defaults to `static`.
     58 *                                                         }
     59 *                                                     }
     60 * @param string|false|null                   $version Optional. String specifying the script module version number. Defaults to false.
     61 *                                                     It is added to the URL as a query string for cache busting purposes. If $version
     62 *                                                     is set to false, the version number is the currently installed WordPress version.
     63 *                                                     If $version is set to null, no version is added.
     64 * @param array<string, string|bool>          $args    {
    6565 *     Optional. An array of additional args. Default empty array.
    6666 *
    … …  
    8282 * @since 6.9.0 Added the $args parameter.
    8383 *
    84  * @param string                     $id      The identifier of the script module. Should be unique. It will be used in the
    85  *                                            final import map.
    86  * @param string                     $src     Optional. Full URL of the script module, or path of the script module relative
    87  *                                            to the WordPress root directory. If it is provided and the script module has
    88  *                                            not been registered yet, it will be registered.
    89  * @param array<string|array>        $deps    {
    90  *                                                Optional. List of dependencies.
    91  *
    92  *                                                @type string|array ...$0 {
    93  *                                                    An array of script module identifiers of the dependencies of this script
    94  *                                                    module. The dependencies can be strings or arrays. If they are arrays,
    95  *                                                    they need an `id` key with the script module identifier, and can contain
    96  *                                                    an `import` key with either `static` or `dynamic`. By default,
    97  *                                                    dependencies that don't contain an `import` key are considered static.
    98  *
    99  *                                                    @type string $id     The script module identifier.
    100  *                                                    @type string $import Optional. Import type. May be either `static` or
    101  *                                                                         `dynamic`. Defaults to `static`.
    102  *                                                }
    103  *                                            }
    104  * @param string|false|null          $version Optional. String specifying the script module version number. Defaults to false.
    105  *                                            It is added to the URL as a query string for cache busting purposes. If $version
    106  *                                            is set to false, the version number is the currently installed WordPress version.
    107  *                                            If $version is set to null, no version is added.
    108  * @param array<string, string|bool> $args    {
     84 * @param string                              $id      The identifier of the script module. Should be unique. It will be used in the
     85 *                                                     final import map.
     86 * @param string                              $src     Optional. Full URL of the script module, or path of the script module relative
     87 *                                                     to the WordPress root directory. If it is provided and the script module has
     88 *                                                     not been registered yet, it will be registered.
     89 * @param array<string|array<string, string>> $deps    {
     90 *                                                         Optional. List of dependencies.
     91 *
     92 *                                                         @type string|array<string, string> ...$0 {
     93 *                                                             An array of script module identifiers of the dependencies of this script
     94 *                                                             module. The dependencies can be strings or arrays. If they are arrays,
     95 *                                                             they need an `id` key with the script module identifier, and can contain
     96 *                                                             an `import` key with either `static` or `dynamic`. By default,
     97 *                                                             dependencies that don't contain an `import` key are considered static.
     98 *
     99 *                                                             @type string $id     The script module identifier.
     100 *                                                             @type string $import Optional. Import type. May be either `static` or
     101 *                                                                                  `dynamic`. Defaults to `static`.
     102 *                                                         }
     103 *                                                     }
     104 * @param string|false|null                   $version Optional. String specifying the script module version number. Defaults to false.
     105 *                                                     It is added to the URL as a query string for cache busting purposes. If $version
     106 *                                                     is set to false, the version number is the currently installed WordPress version.
     107 *                                                     If $version is set to null, no version is added.
     108 * @param array<string, string|bool>          $args    {
    109109 *     Optional. An array of additional args. Default empty array.
    110110 *

  • trunk/tests/phpunit/tests/dependencies/scripts.php

    r61539 r61587  
    107107
    108108    /**
     109     * Tests that scripts trigger _doing_it_wrong for unrecognized keys in the $args array.
     110     *
     111     * @ticket 63486
     112     *
     113     * @covers ::wp_register_script
     114     * @covers ::wp_enqueue_script
     115     * @covers ::_wp_scripts_add_args_data
     116     *
     117     * @dataProvider data_unrecognized_keys_in_args
     118     *
     119     * @param string $function_name Function name to call.
     120     * @param array  $args          Arguments to pass to the function.
     121     * @param string $expected_msg  Expected error message substring.
     122     */
     123    public function test_unrecognized_keys_in_args( string $function_name, array $args, string $expected_msg ) {
     124        $this->setExpectedIncorrectUsage( $function_name );
     125
     126        call_user_func_array( $function_name, $args );
     127
     128        $this->assertStringContainsString(
     129            $expected_msg,
     130            $this->caught_doing_it_wrong[ $function_name ]
     131        );
     132    }
     133
     134    /**
     135     * Data provider for test_unrecognized_keys_in_args.
     136     *
     137     * @return array<string, array{function_name: string, args: array, expected_msg: string}>
     138     */
     139    public function data_unrecognized_keys_in_args(): array {
     140        return array(
     141            'register_script' => array(
     142                'function_name' => 'wp_register_script',
     143                'args'          => array(
     144                    'unrecognized-key-register',
     145                    '/script.js',
     146                    array(),
     147                    null,
     148                    array(
     149                        'unrecognized_key' => 'value',
     150                        'another_bad_key'  => 'value',
     151                    ),
     152                ),
     153                'expected_msg'  => 'Unrecognized key(s) in the $args param: unrecognized_key, another_bad_key. Supported keys: strategy, in_footer, fetchpriority, module_dependencies',
     154            ),
     155            'enqueue_script'  => array(
     156                'function_name' => 'wp_enqueue_script',
     157                'args'          => array(
     158                    'unrecognized-key-enqueue',
     159                    '/script.js',
     160                    array(),
     161                    null,
     162                    array(
     163                        'strategy'            => 'defer',
     164                        'in_footer'           => true,
     165                        'fetchpriority'       => 'high',
     166                        'module_dependencies' => array( 'foo' ),
     167                        'invalid_key'         => 'bar',
     168                    ),
     169                ),
     170                'expected_msg'  => 'Unrecognized key(s) in the $args param: invalid_key. Supported keys: strategy, in_footer, fetchpriority, module_dependencies',
     171            ),
     172        );
     173    }
     174
     175    /**
    109176     * Test versioning
    110177     *
    … …  
    12761343        wp_register_script( 'alias', false, array(), null, array( 'fetchpriority' => 'low' ) );
    12771344        $this->assertArrayNotHasKey( 'fetchpriority', wp_scripts()->registered['alias']->extra );
     1345    }
     1346
     1347    /**
     1348     * Tests validation of module_dependencies in WP_Scripts::add_data().
     1349     *
     1350     * @ticket 61500
     1351     *
     1352     * @covers WP_Scripts::add_data
     1353     *
     1354     * @dataProvider data_add_data_module_dependencies_validation
     1355     *
     1356     * @param mixed      $data     Data to add.
     1357     * @param string     $message  Expected error message.
     1358     * @param bool       $expected Expected return value.
     1359     * @param array|null $stored   Expected stored value.
     1360     */
     1361    public function test_add_data_module_dependencies_validation( $data, string $message, bool $expected, ?array $stored ) {
     1362        wp_register_script( 'test-script', '/test.js' );
     1363
     1364        $expected_incorrect_usage = 'WP_Scripts::add_data';
     1365        $this->setExpectedIncorrectUsage( $expected_incorrect_usage );
     1366
     1367        $this->assertSame( $expected, wp_scripts()->add_data( 'test-script', 'module_dependencies', $data ) );
     1368        $this->assertStringContainsString( $message, $this->caught_doing_it_wrong[ $expected_incorrect_usage ] );
     1369
     1370        if ( null === $stored ) {
     1371            $this->assertFalse( wp_scripts()->get_data( 'test-script', 'module_dependencies' ) );
     1372        } else {
     1373            $this->assertSame( $stored, wp_scripts()->get_data( 'test-script', 'module_dependencies' ) );
     1374        }
     1375    }
     1376
     1377    /**
     1378     * Data provider.
     1379     *
     1380     * @return array<string, array{data: mixed, message: string, expected: bool, stored: array<string|array<string, string>>|null}>
     1381     */
     1382    public function data_add_data_module_dependencies_validation(): array {
     1383        return array(
     1384            'non-array' => array(
     1385                'data'     => 'not-an-array',
     1386                'message'  => 'The value for "module_dependencies" must be an array',
     1387                'expected' => false,
     1388                'stored'   => null,
     1389            ),
     1390            'bad-items' => array(
     1391                'data'     => array( 'valid', 123, true, array(), array( 'id' => 'valid2' ) ),
     1392                'message'  => 'has one or more of its script module dependencies ("module_dependencies") which are invalid',
     1393                'expected' => true,
     1394                'stored'   => array( 'valid', array( 'id' => 'valid2' ) ),
     1395            ),
     1396        );
    12781397    }
    12791398

  • trunk/tests/phpunit/tests/script-modules/wpScriptModules.php

    r61519 r61587  
    1212class Tests_Script_Modules_WpScriptModules extends WP_UnitTestCase {
    1313
    14     /**
    15      * @var WP_Script_Modules
    16      */
    17     protected $original_script_modules;
    18 
    19     /**
    20      * @var string
    21      */
    22     protected $original_wp_version;
    23 
    24     /**
    25      * Instance of WP_Script_Modules.
    26      *
    27      * @var WP_Script_Modules
    28      */
    29     protected $script_modules;
     14    protected WP_Script_Modules $original_script_modules;
     15
     16    protected string $original_wp_version;
     17
     18    protected ?WP_Scripts $original_wp_scripts;
     19
     20    protected WP_Script_Modules $script_modules;
    3021
    3122    /**
    … …  
    3324     */
    3425    public function set_up() {
    35         global $wp_script_modules, $wp_version;
     26        global $wp_script_modules, $wp_scripts, $wp_version;
    3627        parent::set_up();
    3728        $this->original_script_modules = $wp_script_modules;
    3829        $this->original_wp_version     = $wp_version;
     30        $this->original_wp_scripts     = $wp_scripts ?? null;
    3931        $wp_script_modules             = null;
    4032        $this->script_modules          = wp_script_modules();
     33
     34        $wp_scripts                  = new WP_Scripts();
     35        $wp_scripts->default_version = get_bloginfo( 'version' );
    4136    }
    4237
    … …  
    4540     */
    4641    public function tear_down() {
    47         global $wp_script_modules, $wp_version;
    4842        parent::tear_down();
     43        global $wp_script_modules, $wp_scripts, $wp_version;
    4944        $wp_script_modules = $this->original_script_modules;
    5045        $wp_version        = $this->original_wp_version;
     46        $wp_scripts        = $this->original_wp_scripts;
    5147    }
    5248
    … …  
    19871983
    19881984    /**
     1985     * Tests that script modules identified as dependencies of classic scripts are included in the import map.
     1986     *
     1987     * @ticket 61500
     1988     *
     1989     * @covers WP_Script_Modules::get_import_map
     1990     */
     1991    public function test_included_module_appears_in_importmap() {
     1992        $this->script_modules->register( 'dependency', '/dep.js' );
     1993        $this->script_modules->register( 'example', '/example.js', array( 'dependency' ) );
     1994        $this->script_modules->register( 'example2', '/example2.js' );
     1995
     1996        // Nothing printed now.
     1997        $this->assertSame( array(), $this->get_enqueued_script_modules(), 'Initial enqueued script modules was wrong.' );
     1998        $this->assertSame( array(), $this->get_preloaded_script_modules(), 'Initial module preloads was wrong.' );
     1999        $this->assertSame( array(), $this->get_import_map(), 'Initial import map was wrong.' );
     2000
     2001        // Enqueuing a script with a module dependency should add it to the import map.
     2002        wp_enqueue_script(
     2003            'classic',
     2004            '/classic.js',
     2005            array( 'classic-dependency' ),
     2006            false,
     2007            array(
     2008                'module_dependencies' => array(
     2009                    'example',
     2010                    array(
     2011                        'id' => 'example2',
     2012                    ),
     2013                ),
     2014            )
     2015        );
     2016
     2017        $this->assertSame( array(), $this->get_enqueued_script_modules(), 'Final enqueued script modules was wrong.' );
     2018        $this->assertSame( array(), $this->get_preloaded_script_modules(), 'Final module preloads was wrong.' );
     2019        $this->assertEqualSets(
     2020            array( 'example', 'example2', 'dependency' ),
     2021            array_keys( $this->get_import_map() ),
     2022            'Import map keys were wrong.'
     2023        );
     2024    }
     2025
     2026    /**
     2027     * Tests that dynamic dependencies of enqueued script modules are included in the import map.
     2028     *
     2029     * @ticket 61500
     2030     *
     2031     * @covers WP_Script_Modules::get_import_map
     2032     */
     2033    public function test_import_map_includes_dynamic_dependencies_of_enqueued_modules() {
     2034        $this->script_modules->register( 'dependency-of-enqueued', '/dependency-of-enqueued.js' );
     2035        $this->script_modules->enqueue(
     2036            'enqueued',
     2037            '/enqueued.js',
     2038            array(
     2039                array(
     2040                    'id'     => 'dependency-of-enqueued',
     2041                    'import' => 'dynamic',
     2042                ),
     2043            )
     2044        );
     2045
     2046        $enqueued = $this->get_enqueued_script_modules();
     2047        $this->assertCount( 1, $enqueued, 'Enqueue count was wrong.' );
     2048        $this->assertArrayHasKey( 'enqueued', $enqueued, 'Missing "enqueued" script module enqueue.' );
     2049        $this->assertCount( 0, $this->get_preloaded_script_modules(), 'Module preload count was wrong.' );
     2050        $this->assertEqualSets(
     2051            array( 'dependency-of-enqueued' ),
     2052            array_keys( $this->get_import_map() ),
     2053            'Import map keys were wrong.'
     2054        );
     2055    }
     2056
     2057    /**
     2058     * Tests that script module dependencies of enqueued classic scripts (including transitive ones) are included in the import map.
     2059     *
     2060     * @ticket 61500
     2061     *
     2062     * @covers WP_Script_Modules::get_import_map
     2063     */
     2064    public function test_import_map_includes_dependencies_of_classic_scripts_recursive() {
     2065        $this->script_modules->register( 'classic-transitive-dependency', '/classic-transitive-dependency.js' );
     2066        $this->script_modules->register( 'dependency-of-not-enqueued', '/dependency-of-not-enqueued.js' );
     2067        $this->script_modules->register( 'not-enqueued', '/not-enqueued.js', array( 'dependency-of-not-enqueued' ) );
     2068
     2069        // Enqueuing a script with a module dependency should add it to the import map.
     2070        wp_register_script(
     2071            'classic-transitive-dep',
     2072            '/classic-transitive-dep.js',
     2073            array(),
     2074            false,
     2075            array(
     2076                'module_dependencies' => array( 'classic-transitive-dependency' ),
     2077            )
     2078        );
     2079        wp_enqueue_script(
     2080            'classic',
     2081            '/classic.js',
     2082            array( 'classic-transitive-dep' ),
     2083            false,
     2084            array(
     2085                'module_dependencies' => array( 'not-enqueued' ),
     2086            )
     2087        );
     2088
     2089        $enqueued = $this->get_enqueued_script_modules();
     2090        $this->assertCount( 0, $enqueued, 'Enqueue count was wrong.' );
     2091        $this->assertCount( 0, $this->get_preloaded_script_modules(), 'Module preload count was wrong.' );
     2092        $this->assertEqualSets(
     2093            array(
     2094                'classic-transitive-dependency',
     2095                'not-enqueued',
     2096                'dependency-of-not-enqueued',
     2097            ),
     2098            array_keys( $this->get_import_map() ),
     2099            'Import map keys were wrong.'
     2100        );
     2101    }
     2102
     2103    /**
     2104     * Tests that WP_Scripts emits a _doing_it_wrong() notice for missing script module dependencies.
     2105     *
     2106     * @ticket 61500
     2107     * @ticket 64229
     2108     * @covers WP_Script_Modules::get_import_map
     2109     */
     2110    public function test_wp_scripts_doing_it_wrong_for_missing_script_module_dependencies() {
     2111        $expected_incorrect_usage = 'WP_Scripts::add_data';
     2112        $this->setExpectedIncorrectUsage( $expected_incorrect_usage );
     2113
     2114        wp_enqueue_script(
     2115            'registered-dep',
     2116            '/registered-dep.js',
     2117            array(),
     2118            null,
     2119            array(
     2120                'module_dependencies' => array( 'does-not-exist' ),
     2121            )
     2122        );
     2123
     2124        $import_map = $this->get_import_map();
     2125        $this->assertSame( array(), $import_map, 'Expected importmap to be empty.' );
     2126        $markup = get_echo( 'wp_print_scripts' );
     2127
     2128        /*
     2129         * In the future, we may want to have missing script module dependencies for classic scripts to cause the
     2130         * classic script to not be printed. This would align the behavior with script modules that have missing
     2131         * script module dependencies, and classic scripts that have missing classic script dependencies. Nevertheless,
     2132         * since script module dependencies rely on dynamic imports, the dependency may not be as strong. This means
     2133         * the classic script may still work or have a fallback in case the script module fails to dynamically import.
     2134         * This same change could be made for script modules as well, where if a script module has a missing dynamic
     2135         * script module dependency, this might similarly not be sufficient reason to omit printing the dependent script module.
     2136         */
     2137        $this->assertStringContainsString( 'registered-dep.js', $markup, 'Expected script to be present, even though it has a missing script module dependency.' );
     2138
     2139        $this->assertArrayHasKey(
     2140            $expected_incorrect_usage,
     2141            $this->caught_doing_it_wrong,
     2142            "Expected $expected_incorrect_usage to trigger a _doing_it_wrong() notice for missing dependency."
     2143        );
     2144
     2145        $this->assertStringContainsString(
     2146            'The script with the handle "registered-dep" was enqueued with script module dependencies ("module_dependencies") that are not registered: does-not-exist',
     2147            $this->caught_doing_it_wrong[ $expected_incorrect_usage ],
     2148            'Expected _doing_it_wrong() notice to indicate missing script module dependencies for enqueued script.'
     2149        );
     2150    }
     2151
     2152    /**
    19892153     * Tests various ways of printing and dependency ordering of script modules.
    19902154     *
Note: See TracChangeset for help on using the changeset viewer.