WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
01/23/2024 03:32:03 AM (11 months ago)
Author:
dmsnell
Message:

Script Modules API: Rename wp_module to wp_script_module

Renames all mentions to "module" with "script module", including function names, comments, and tests.

Follow up to [57269]

The list of functions renamed are:

  • wp_module() -> wp_script_module().
  • wp_register_module() -> wp_register_script_module().
  • wp_enqueue_module() -> wp_enqueue_script_module().
  • wp_dequeue_module() -> wp_dequeue_script_module().
  • WP_Script_Modules::print_enqueued_modules() -> WP_Script_Modules::print_enqueued_script_modules().
  • WP_Script_Modules::print_module_preloads() -> WP_Script_Modules::print_script_module_preloads().

It also adds PHP 7 typing to all the functions and improves the types of the $deps argument of wp_register_script_module() and wp_enqueue_script_module() using @type.

Props luisherranz, idad5, costdev, nefff, joemcgill, jorbin, swisspidy, jonsurrel, flixos90, gziolo, westonruter, bernhard-reiter, kamranzafar4343
See #56313

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r57271 r57327  
    11<?php
    22/**
    3  * Modules API: WP_Script_Modules class.
     3 * Script Modules API: WP_Script_Modules class.
    44 *
    55 * Native support for ES Modules and Import Maps.
    … …  
    1010
    1111/**
    12  * Core class used to register modules.
     12 * Core class used to register script modules.
    1313 *
    1414 * @since 6.5.0
    … …  
    1616class WP_Script_Modules {
    1717    /**
    18      * Holds the registered modules, keyed by module identifier.
     18     * Holds the registered script modules, keyed by script module identifier.
    1919     *
    2020     * @since 6.5.0
    … …  
    2424
    2525    /**
    26      * Holds the module identifiers that were enqueued before registered.
    27      *
    28      * @since 6.5.0
    29      * @var array
     26     * Holds the script module identifiers that were enqueued before registered.
     27     *
     28     * @since 6.5.0
     29     * @var array<string, true>
    3030     */
    3131    private $enqueued_before_registered = array();
    3232
    3333    /**
    34      * Registers the module if no module with that module identifier has already
    35      * been registered.
    36      *
    37      * @since 6.5.0
    38      *
    39      * @param string                                                        $module_id The identifier of the module.
    40      *                                                                                 Should be unique. It will be used
    41      *                                                                                 in the final import map.
    42      * @param string                                                        $src       Full URL of the module, or path of
    43      *                                                                                 the module relative to the
    44      *                                                                                 WordPress root directory.
    45      * @param array<string|array{id: string, import?: 'static'|'dynamic' }> $deps      Optional. An array of module
    46      *                                                                                 identifiers of the dependencies of
    47      *                                                                                 this module. The dependencies can
    48      *                                                                                 be strings or arrays. If they are
    49      *                                                                                 arrays, they need an `id` key with
    50      *                                                                                 the module identifier, and can
    51      *                                                                                 contain an `import` key with either
    52      *                                                                                 `static` or `dynamic`. By default,
    53      *                                                                                 dependencies that don't contain an
    54      *                                                                                 `import` key are considered static.
    55      * @param string|false|null                                             $version   Optional. String specifying the
    56      *                                                                                 module version number. Defaults to
    57      *                                                                                 false. It is added to the URL as a
    58      *                                                                                 query string for cache busting
    59      *                                                                                 purposes. If $version is set to
    60      *                                                                                 false, the version number is the
    61      *                                                                                 currently installed WordPress
    62      *                                                                                 version. If $version is set to
    63      *                                                                                 null, no version is added.
    64      */
    65     public function register( $module_id, $src, $deps = array(), $version = false ) {
    66         if ( ! isset( $this->registered[ $module_id ] ) ) {
     34     * Registers the script module if no script module with that script module
     35     * identifier has already been registered.
     36     *
     37     * @since 6.5.0
     38     *
     39     * @param string            $id       The identifier of the script module. Should be unique. It will be used in the
     40     *                                    final import map.
     41     * @param string            $src      Optional. Full URL of the script module, or path of the script module relative
     42     *                                    to the WordPress root directory. If it is provided and the script module has
     43     *                                    not been registered yet, it will be registered.
     44     * @param array             $deps     {
     45     *                                        Optional. List of dependencies.
     46     *
     47     *                                        @type string|array $0... {
     48     *                                            An array of script module identifiers of the dependencies of this script
     49     *                                            module. The dependencies can be strings or arrays. If they are arrays,
     50     *                                            they need an `id` key with the script module identifier, and can contain
     51     *                                            an `import` key with either `static` or `dynamic`. By default,
     52     *                                            dependencies that don't contain an `import` key are considered static.
     53     *
     54     *                                            @type string $id     The script module identifier.
     55     *                                            @type string $import Optional. Import type. May be either `static` or
     56     *                                                                 `dynamic`. Defaults to `static`.
     57     *                                        }
     58     *                                    }
     59     * @param string|false|null $version  Optional. String specifying the script module version number. Defaults to false.
     60     *                                    It is added to the URL as a query string for cache busting purposes. If $version
     61     *                                    is set to false, the version number is the currently installed WordPress version.
     62     *                                    If $version is set to null, no version is added.
     63     */
     64    public function register( string $id, string $src, array $deps = array(), $version = false ) {
     65        if ( ! isset( $this->registered[ $id ] ) ) {
    6766            $dependencies = array();
    6867            foreach ( $deps as $dependency ) {
    … …  
    8685            }
    8786
    88             $this->registered[ $module_id ] = array(
     87            $this->registered[ $id ] = array(
    8988                'src'          => $src,
    9089                'version'      => $version,
    91                 'enqueue'      => isset( $this->enqueued_before_registered[ $module_id ] ),
     90                'enqueue'      => isset( $this->enqueued_before_registered[ $id ] ),
    9291                'dependencies' => $dependencies,
    9392                'enqueued'     => false,
    … …  
    9897
    9998    /**
    100      * Marks the module to be enqueued in the page the next time
    101      * `prints_enqueued_modules` is called.
    102      *
    103      * If a src is provided and the module has not been registered yet, it will be
    104      * registered.
    105      *
    106      * @since 6.5.0
    107      *
    108      * @param string                                                        $module_id The identifier of the module.
    109      *                                                                                 Should be unique. It will be used
    110      *                                                                                 in the final import map.
    111      * @param string                                                        $src       Optional. Full URL of the module,
    112      *                                                                                 or path of the module relative to
    113      *                                                                                 the WordPress root directory. If
    114      *                                                                                 it is provided and the module has
    115      *                                                                                 not been registered yet, it will be
    116      *                                                                                 registered.
    117      * @param array<string|array{id: string, import?: 'static'|'dynamic' }> $deps      Optional. An array of module
    118      *                                                                                 identifiers of the dependencies of
    119      *                                                                                 this module. The dependencies can
    120      *                                                                                 be strings or arrays. If they are
    121      *                                                                                 arrays, they need an `id` key with
    122      *                                                                                 the module identifier, and can
    123      *                                                                                 contain an `import` key with either
    124      *                                                                                 `static` or `dynamic`. By default,
    125      *                                                                                 dependencies that don't contain an
    126      *                                                                                 `import` key are considered static.
    127      * @param string|false|null                                             $version   Optional. String specifying the
    128      *                                                                                 module version number. Defaults to
    129      *                                                                                 false. It is added to the URL as a
    130      *                                                                                 query string for cache busting
    131      *                                                                                 purposes. If $version is set to
    132      *                                                                                 false, the version number is the
    133      *                                                                                 currently installed WordPress
    134      *                                                                                 version. If $version is set to
    135      *                                                                                 null, no version is added.
    136      */
    137     public function enqueue( $module_id, $src = '', $deps = array(), $version = false ) {
    138         if ( isset( $this->registered[ $module_id ] ) ) {
    139             $this->registered[ $module_id ]['enqueue'] = true;
     99     * Marks the script module to be enqueued in the page the next time
     100     * `print_enqueued_script_modules` is called.
     101     *
     102     * If a src is provided and the script module has not been registered yet, it
     103     * will be registered.
     104     *
     105     * @since 6.5.0
     106     *
     107     * @param string            $id       The identifier of the script module. Should be unique. It will be used in the
     108     *                                    final import map.
     109     * @param string            $src      Optional. Full URL of the script module, or path of the script module relative
     110     *                                    to the WordPress root directory. If it is provided and the script module has
     111     *                                    not been registered yet, it will be registered.
     112     * @param array             $deps     {
     113     *                                        Optional. List of dependencies.
     114     *
     115     *                                        @type string|array $0... {
     116     *                                            An array of script module identifiers of the dependencies of this script
     117     *                                            module. The dependencies can be strings or arrays. If they are arrays,
     118     *                                            they need an `id` key with the script module identifier, and can contain
     119     *                                            an `import` key with either `static` or `dynamic`. By default,
     120     *                                            dependencies that don't contain an `import` key are considered static.
     121     *
     122     *                                            @type string $id     The script module identifier.
     123     *                                            @type string $import Optional. Import type. May be either `static` or
     124     *                                                                 `dynamic`. Defaults to `static`.
     125     *                                        }
     126     *                                    }
     127     * @param string|false|null $version  Optional. String specifying the script module version number. Defaults to false.
     128     *                                    It is added to the URL as a query string for cache busting purposes. If $version
     129     *                                    is set to false, the version number is the currently installed WordPress version.
     130     *                                    If $version is set to null, no version is added.
     131     */
     132    public function enqueue( string $id, string $src = '', array $deps = array(), $version = false ) {
     133        if ( isset( $this->registered[ $id ] ) ) {
     134            $this->registered[ $id ]['enqueue'] = true;
    140135        } elseif ( $src ) {
    141             $this->register( $module_id, $src, $deps, $version );
    142             $this->registered[ $module_id ]['enqueue'] = true;
     136            $this->register( $id, $src, $deps, $version );
     137            $this->registered[ $id ]['enqueue'] = true;
    143138        } else {
    144             $this->enqueued_before_registered[ $module_id ] = true;
    145         }
    146     }
    147 
    148     /**
    149      * Unmarks the module so it will no longer be enqueued in the page.
    150      *
    151      * @since 6.5.0
    152      *
    153      * @param string $module_id The identifier of the module.
    154      */
    155     public function dequeue( $module_id ) {
    156         if ( isset( $this->registered[ $module_id ] ) ) {
    157             $this->registered[ $module_id ]['enqueue'] = false;
    158         }
    159         unset( $this->enqueued_before_registered[ $module_id ] );
    160     }
    161 
    162     /**
    163      * Adds the hooks to print the import map, enqueued modules and module
    164      * preloads.
    165      *
    166      * It adds the actions to print the enqueued modules and module preloads to
    167      * both `wp_head` and `wp_footer` because in classic themes, the modules
    168      * used by the theme and plugins will likely be able to be printed in the
    169      * `head`, but the ones used by the blocks will need to be enqueued in the
    170      * `footer`.
    171      *
    172      * As all modules are deferred and dependencies are handled by the browser,
    173      * the order of the modules is not important, but it's still better to print
    174      * the ones that are available when the `wp_head` is rendered, so the browser
    175      * starts downloading those as soon as possible.
     139            $this->enqueued_before_registered[ $id ] = true;
     140        }
     141    }
     142
     143    /**
     144     * Unmarks the script module so it will no longer be enqueued in the page.
     145     *
     146     * @since 6.5.0
     147     *
     148     * @param string $id The identifier of the script module.
     149     */
     150    public function dequeue( string $id ) {
     151        if ( isset( $this->registered[ $id ] ) ) {
     152            $this->registered[ $id ]['enqueue'] = false;
     153        }
     154        unset( $this->enqueued_before_registered[ $id ] );
     155    }
     156
     157    /**
     158     * Adds the hooks to print the import map, enqueued script modules and script
     159     * module preloads.
     160     *
     161     * It adds the actions to print the enqueued script modules and script module
     162     * preloads to both `wp_head` and `wp_footer` because in classic themes, the
     163     * script modules used by the theme and plugins will likely be able to be
     164     * printed in the `head`, but the ones used by the blocks will need to be
     165     * enqueued in the `footer`.
     166     *
     167     * As all script modules are deferred and dependencies are handled by the
     168     * browser, the order of the script modules is not important, but it's still
     169     * better to print the ones that are available when the `wp_head` is rendered,
     170     * so the browser starts downloading those as soon as possible.
    176171     *
    177172     * The import map is also printed in the footer to be able to include the
    178      * dependencies of all the modules, including the ones printed in the footer.
     173     * dependencies of all the script modules, including the ones printed in the
     174     * footer.
    179175     *
    180176     * @since 6.5.0
    181177     */
    182178    public function add_hooks() {
    183         add_action( 'wp_head', array( $this, 'print_enqueued_modules' ) );
    184         add_action( 'wp_head', array( $this, 'print_module_preloads' ) );
    185         add_action( 'wp_footer', array( $this, 'print_enqueued_modules' ) );
    186         add_action( 'wp_footer', array( $this, 'print_module_preloads' ) );
     179        add_action( 'wp_head', array( $this, 'print_enqueued_script_modules' ) );
     180        add_action( 'wp_head', array( $this, 'print_script_module_preloads' ) );
     181        add_action( 'wp_footer', array( $this, 'print_enqueued_script_modules' ) );
     182        add_action( 'wp_footer', array( $this, 'print_script_module_preloads' ) );
    187183        add_action( 'wp_footer', array( $this, 'print_import_map' ) );
    188184    }
    189185
    190186    /**
    191      * Prints the enqueued modules using script tags with type="module"
     187     * Prints the enqueued script modules using script tags with type="module"
    192188     * attributes.
    193189     *
    194      * If a enqueued module has already been printed, it will not be printed again
    195      * on subsequent calls to this function.
    196      *
    197      * @since 6.5.0
    198      */
    199     public function print_enqueued_modules() {
    200         foreach ( $this->get_marked_for_enqueue() as $module_id => $module ) {
    201             if ( false === $module['enqueued'] ) {
     190     * If a enqueued script module has already been printed, it will not be
     191     * printed again on subsequent calls to this function.
     192     *
     193     * @since 6.5.0
     194     */
     195    public function print_enqueued_script_modules() {
     196        foreach ( $this->get_marked_for_enqueue() as $id => $script_module ) {
     197            if ( false === $script_module['enqueued'] ) {
    202198                // Mark it as enqueued so it doesn't get enqueued again.
    203                 $this->registered[ $module_id ]['enqueued'] = true;
     199                $this->registered[ $id ]['enqueued'] = true;
    204200
    205201                wp_print_script_tag(
    206202                    array(
    207203                        'type' => 'module',
    208                         'src'  => $this->get_versioned_src( $module ),
    209                         'id'   => $module_id . '-js-module',
     204                        'src'  => $this->get_versioned_src( $script_module ),
     205                        'id'   => $id . '-js-module',
    210206                    )
    211207                );
    … …  
    215211
    216212    /**
    217      * Prints the the static dependencies of the enqueued modules using link tags
    218      * with rel="modulepreload" attributes.
    219      *
    220      * If a module is marked for enqueue, it will not be preloaded. If a preloaded
    221      * module has already been printed, it will not be printed again on subsequent
    222      * calls to this function.
    223      *
    224      * @since 6.5.0
    225      */
    226     public function print_module_preloads() {
    227         foreach ( $this->get_dependencies( array_keys( $this->get_marked_for_enqueue() ), array( 'static' ) ) as $module_id => $module ) {
     213     * Prints the the static dependencies of the enqueued script modules using
     214     * link tags with rel="modulepreload" attributes.
     215     *
     216     * If a script module is marked for enqueue, it will not be preloaded. If a
     217     * preloaded script module has already been printed, it will not be printed
     218     * again on subsequent calls to this function.
     219     *
     220     * @since 6.5.0
     221     */
     222    public function print_script_module_preloads() {
     223        foreach ( $this->get_dependencies( array_keys( $this->get_marked_for_enqueue() ), array( 'static' ) ) as $id => $script_module ) {
    228224            // Don't preload if it's marked for enqueue or has already been preloaded.
    229             if ( true !== $module['enqueue'] && false === $module['preloaded'] ) {
     225            if ( true !== $script_module['enqueue'] && false === $script_module['preloaded'] ) {
    230226                // Mark it as preloaded so it doesn't get preloaded again.
    231                 $this->registered[ $module_id ]['preloaded'] = true;
     227                $this->registered[ $id ]['preloaded'] = true;
    232228
    233229                echo sprintf(
    234230                    '<link rel="modulepreload" href="%s" id="%s">',
    235                     esc_url( $this->get_versioned_src( $module ) ),
    236                     esc_attr( $module_id . '-js-modulepreload' )
     231                    esc_url( $this->get_versioned_src( $script_module ) ),
     232                    esc_attr( $id . '-js-modulepreload' )
    237233                );
    238234            }
    … …  
    263259     * @since 6.5.0
    264260     *
    265      * @return array Array with an `imports` key mapping to an array of module identifiers and their respective URLs,
    266      *               including the version query.
    267      */
    268     private function get_import_map() {
     261     * @return array Array with an `imports` key mapping to an array of script module identifiers and their respective
     262     *               URLs, including the version query.
     263     */
     264    private function get_import_map(): array {
    269265        $imports = array();
    270         foreach ( $this->get_dependencies( array_keys( $this->get_marked_for_enqueue() ) ) as $module_id => $module ) {
    271             $imports[ $module_id ] = $this->get_versioned_src( $module );
     266        foreach ( $this->get_dependencies( array_keys( $this->get_marked_for_enqueue() ) ) as $id => $script_module ) {
     267            $imports[ $id ] = $this->get_versioned_src( $script_module );
    272268        }
    273269        return array( 'imports' => $imports );
    … …  
    275271
    276272    /**
    277      * Retrieves the list of modules marked for enqueue.
    278      *
    279      * @since 6.5.0
    280      *
    281      * @return array Modules marked for enqueue, keyed by module identifier.
    282      */
    283     private function get_marked_for_enqueue() {
     273     * Retrieves the list of script modules marked for enqueue.
     274     *
     275     * @since 6.5.0
     276     *
     277     * @return array Script modules marked for enqueue, keyed by script module identifier.
     278     */
     279    private function get_marked_for_enqueue(): array {
    284280        $enqueued = array();
    285         foreach ( $this->registered as $module_id => $module ) {
    286             if ( true === $module['enqueue'] ) {
    287                 $enqueued[ $module_id ] = $module;
     281        foreach ( $this->registered as $id => $script_module ) {
     282            if ( true === $script_module['enqueue'] ) {
     283                $enqueued[ $id ] = $script_module;
    288284            }
    289285        }
    … …  
    292288
    293289    /**
    294      * Retrieves all the dependencies for the given module identifiers, filtered
    295      * by import types.
     290     * Retrieves all the dependencies for the given script module identifiers,
     291     * filtered by import types.
    296292     *
    297293     * It will consolidate an array containing a set of unique dependencies based
    … …  
    301297     * @since 6.5.0
    302298     *
    303      * @param array $module_ids   The identifiers of the modules for which to gather dependencies.
    304      * @param array $import_types Optional. Import types of dependencies to retrieve: 'static', 'dynamic', or both.
    305      *                            Default is both.
    306      * @return array List of dependencies, keyed by module identifier.
    307      */
    308     private function get_dependencies( $module_ids, $import_types = array( 'static', 'dynamic' ) ) {
     299
     300     * @param string[] $ids          The identifiers of the script modules for which to gather dependencies.
     301     * @param array    $import_types Optional. Import types of dependencies to retrieve: 'static', 'dynamic', or both.
     302     *                               Default is both.
     303     * @return array List of dependencies, keyed by script module identifier.
     304     */
     305    private function get_dependencies( array $ids, array $import_types = array( 'static', 'dynamic' ) ) {
    309306        return array_reduce(
    310             $module_ids,
    311             function ( $dependency_modules, $module_id ) use ( $import_types ) {
     307            $ids,
     308            function ( $dependency_script_modules, $id ) use ( $import_types ) {
    312309                $dependencies = array();
    313                 foreach ( $this->registered[ $module_id ]['dependencies'] as $dependency ) {
     310                foreach ( $this->registered[ $id ]['dependencies'] as $dependency ) {
    314311                    if (
    315312                    in_array( $dependency['import'], $import_types, true ) &&
    316313                    isset( $this->registered[ $dependency['id'] ] ) &&
    317                     ! isset( $dependency_modules[ $dependency['id'] ] )
     314                    ! isset( $dependency_script_modules[ $dependency['id'] ] )
    318315                    ) {
    319316                        $dependencies[ $dependency['id'] ] = $this->registered[ $dependency['id'] ];
    320317                    }
    321318                }
    322                 return array_merge( $dependency_modules, $dependencies, $this->get_dependencies( array_keys( $dependencies ), $import_types ) );
     319                return array_merge( $dependency_script_modules, $dependencies, $this->get_dependencies( array_keys( $dependencies ), $import_types ) );
    323320            },
    324321            array()
    … …  
    327324
    328325    /**
    329      * Gets the versioned URL for a module src.
     326     * Gets the versioned URL for a script module src.
    330327     *
    331328     * If $version is set to false, the version number is the currently installed
    … …  
    335332     * @since 6.5.0
    336333     *
    337      * @param array $module The module.
    338      * @return string The module src with a version if relevant.
    339      */
    340     private function get_versioned_src( array $module ) {
     334     * @param array $script_module The script module.
     335     * @return string The script module src with a version if relevant.
     336     */
     337    private function get_versioned_src( array $script_module ): string {
    341338        $args = array();
    342         if ( false === $module['version'] ) {
     339        if ( false === $script_module['version'] ) {
    343340            $args['ver'] = get_bloginfo( 'version' );
    344         } elseif ( null !== $module['version'] ) {
    345             $args['ver'] = $module['version'];
     341        } elseif ( null !== $script_module['version'] ) {
     342            $args['ver'] = $script_module['version'];
    346343        }
    347344        if ( $args ) {
    348             return add_query_arg( $args, $module['src'] );
    349         }
    350         return $module['src'];
     345            return add_query_arg( $args, $script_module['src'] );
     346        }
     347        return $script_module['src'];
    351348    }
    352349}
Note: See TracChangeset for help on using the changeset viewer.