[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Script Modules API: Script Module functions
   4   *
   5   * @since 6.5.0
   6   *
   7   * @package WordPress
   8   * @subpackage Script Modules
   9   */
  10  
  11  /**
  12   * Retrieves the main WP_Script_Modules instance.
  13   *
  14   * This function provides access to the WP_Script_Modules instance, creating one
  15   * if it doesn't exist yet.
  16   *
  17   * @since 6.5.0
  18   *
  19   * @global WP_Script_Modules $wp_script_modules
  20   *
  21   * @return WP_Script_Modules The main WP_Script_Modules instance.
  22   */
  23  function wp_script_modules(): WP_Script_Modules {
  24      global $wp_script_modules;
  25  
  26      if ( ! ( $wp_script_modules instanceof WP_Script_Modules ) ) {
  27          $wp_script_modules = new WP_Script_Modules();
  28      }
  29  
  30      return $wp_script_modules;
  31  }
  32  
  33  /**
  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   * @since 6.9.0 Added the $args parameter.
  39   *
  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    {
  65   *     Optional. An array of additional args. Default empty array.
  66   *
  67   *     @type bool                $in_footer     Whether to print the script module in the footer. Only relevant to block themes. Default 'false'. Optional.
  68   *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
  69   * }
  70   */
  71  function wp_register_script_module( string $id, string $src, array $deps = array(), $version = false, array $args = array() ) {
  72      wp_script_modules()->register( $id, $src, $deps, $version, $args );
  73  }
  74  
  75  /**
  76   * Marks the script module to be enqueued in the page.
  77   *
  78   * If a src is provided and the script module has not been registered yet, it
  79   * will be registered.
  80   *
  81   * @since 6.5.0
  82   * @since 6.9.0 Added the $args parameter.
  83   *
  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    {
 109   *     Optional. An array of additional args. Default empty array.
 110   *
 111   *     @type bool                $in_footer     Whether to print the script module in the footer. Only relevant to block themes. Default 'false'. Optional.
 112   *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
 113   * }
 114   */
 115  function wp_enqueue_script_module( string $id, string $src = '', array $deps = array(), $version = false, array $args = array() ) {
 116      wp_script_modules()->enqueue( $id, $src, $deps, $version, $args );
 117  }
 118  
 119  /**
 120   * Unmarks the script module so it is no longer enqueued in the page.
 121   *
 122   * @since 6.5.0
 123   *
 124   * @param string $id The identifier of the script module.
 125   */
 126  function wp_dequeue_script_module( string $id ) {
 127      wp_script_modules()->dequeue( $id );
 128  }
 129  
 130  /**
 131   * Deregisters the script module.
 132   *
 133   * @since 6.5.0
 134   *
 135   * @param string $id The identifier of the script module.
 136   */
 137  function wp_deregister_script_module( string $id ) {
 138      wp_script_modules()->deregister( $id );
 139  }
 140  
 141  /**
 142   * Registers all the default WordPress Script Modules.
 143   *
 144   * @since 6.7.0
 145   */
 146  function wp_default_script_modules() {
 147      $suffix = defined( 'WP_RUN_CORE_TESTS' ) ? '.min' : wp_scripts_get_suffix();
 148  
 149      /*
 150       * Expects multidimensional array like:
 151       *
 152       *     'interactivity/index.min.js' => array('dependencies' => array(…), 'version' => '…'),
 153       *     'interactivity-router/index.min.js' => array('dependencies' => array(…), 'version' => '…'),
 154       *     'block-library/navigation/view.min.js' => …
 155       */
 156      $assets = include ABSPATH . WPINC . "/assets/script-modules-packages{$suffix}.php";
 157  
 158      foreach ( $assets as $file_name => $script_module_data ) {
 159          /*
 160           * Build the WordPress Script Module ID from the file name.
 161           * Prepend `@wordpress/` and remove extensions and `/index` if present:
 162           *   - interactivity/index.min.js         => @wordpress/interactivity
 163           *   - interactivity-router/index.min.js  => @wordpress/interactivity-router
 164           *   - block-library/navigation/view.js   => @wordpress/block-library/navigation/view
 165           */
 166          $script_module_id = '@wordpress/' . preg_replace( '~(?:/index)?(?:\.min)?\.js$~D', '', $file_name, 1 );
 167  
 168          /*
 169           * The Interactivity API is designed with server-side rendering as its primary goal, so all of its script modules
 170           * should be loaded with low fetchpriority and printed in the footer since they should not be needed in the
 171           * critical rendering path. Also, the @wordpress/a11y script module is intended to be used as a dynamic import
 172           * dependency, in which case the fetchpriority is irrelevant. See <https://make.wordpress.org/core/2024/10/14/updates-to-script-modules-in-6-7/>.
 173           * However, in case it is added as a static import dependency, the fetchpriority is explicitly set to be 'low'
 174           * since the module should not be involved in the critical rendering path, and if it is, its fetchpriority will
 175           * be bumped to match the fetchpriority of the dependent script.
 176           */
 177          $args = array();
 178          if (
 179              str_starts_with( $script_module_id, '@wordpress/interactivity' ) ||
 180              str_starts_with( $script_module_id, '@wordpress/block-library' ) ||
 181              '@wordpress/a11y' === $script_module_id
 182          ) {
 183              $args['fetchpriority'] = 'low';
 184              $args['in_footer']     = true;
 185          }
 186  
 187          // Marks all Core blocks as compatible with client-side navigation.
 188          if ( str_starts_with( $script_module_id, '@wordpress/block-library' ) ) {
 189              wp_interactivity()->add_client_navigation_support_to_script_module( $script_module_id );
 190          }
 191  
 192          $path        = includes_url( "js/dist/script-modules/{$file_name}" );
 193          $module_deps = $script_module_data['module_dependencies'] ?? array();
 194          wp_register_script_module( $script_module_id, $path, $module_deps, $script_module_data['version'], $args );
 195      }
 196  }
 197  
 198  /**
 199   * Enqueues script modules required by the block editor.
 200   *
 201   * @since 6.9.0
 202   */
 203  function wp_enqueue_block_editor_script_modules() {
 204      /*
 205       * Enqueue the LaTeX to MathML loader for the math block editor.
 206       * The loader dynamically imports the main LaTeX to MathML module when needed.
 207       */
 208      wp_enqueue_script_module( '@wordpress/latex-to-mathml/loader' );
 209  }