[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             $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             $args    {
  65   *     Optional. An array of additional args. Default empty array.
  66   *
  67   *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
  68   * }
  69   */
  70  function wp_register_script_module( string $id, string $src, array $deps = array(), $version = false, array $args = array() ) {
  71      wp_script_modules()->register( $id, $src, $deps, $version, $args );
  72  }
  73  
  74  /**
  75   * Marks the script module to be enqueued in the page.
  76   *
  77   * If a src is provided and the script module has not been registered yet, it
  78   * will be registered.
  79   *
  80   * @since 6.5.0
  81   * @since 6.9.0 Added the $args parameter.
  82   *
  83   * @param string            $id      The identifier of the script module. Should be unique. It will be used in the
  84   *                                   final import map.
  85   * @param string            $src     Optional. Full URL of the script module, or path of the script module relative
  86   *                                   to the WordPress root directory. If it is provided and the script module has
  87   *                                   not been registered yet, it will be registered.
  88   * @param array             $deps    {
  89   *                                       Optional. List of dependencies.
  90   *
  91   *                                       @type string|array ...$0 {
  92   *                                           An array of script module identifiers of the dependencies of this script
  93   *                                           module. The dependencies can be strings or arrays. If they are arrays,
  94   *                                           they need an `id` key with the script module identifier, and can contain
  95   *                                           an `import` key with either `static` or `dynamic`. By default,
  96   *                                           dependencies that don't contain an `import` key are considered static.
  97   *
  98   *                                           @type string $id     The script module identifier.
  99   *                                           @type string $import Optional. Import type. May be either `static` or
 100   *                                                                `dynamic`. Defaults to `static`.
 101   *                                       }
 102   *                                   }
 103   * @param string|false|null $version Optional. String specifying the script module version number. Defaults to false.
 104   *                                   It is added to the URL as a query string for cache busting purposes. If $version
 105   *                                   is set to false, the version number is the currently installed WordPress version.
 106   *                                   If $version is set to null, no version is added.
 107   * @param array             $args    {
 108   *     Optional. An array of additional args. Default empty array.
 109   *
 110   *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
 111   * }
 112   */
 113  function wp_enqueue_script_module( string $id, string $src = '', array $deps = array(), $version = false, array $args = array() ) {
 114      wp_script_modules()->enqueue( $id, $src, $deps, $version, $args );
 115  }
 116  
 117  /**
 118   * Unmarks the script module so it is no longer enqueued in the page.
 119   *
 120   * @since 6.5.0
 121   *
 122   * @param string $id The identifier of the script module.
 123   */
 124  function wp_dequeue_script_module( string $id ) {
 125      wp_script_modules()->dequeue( $id );
 126  }
 127  
 128  /**
 129   * Deregisters the script module.
 130   *
 131   * @since 6.5.0
 132   *
 133   * @param string $id The identifier of the script module.
 134   */
 135  function wp_deregister_script_module( string $id ) {
 136      wp_script_modules()->deregister( $id );
 137  }
 138  
 139  /**
 140   * Registers all the default WordPress Script Modules.
 141   *
 142   * @since 6.7.0
 143   */
 144  function wp_default_script_modules() {
 145      $suffix = defined( 'WP_RUN_CORE_TESTS' ) ? '.min' : wp_scripts_get_suffix();
 146  
 147      /*
 148       * Expects multidimensional array like:
 149       *
 150       *     'interactivity/index.min.js' => array('dependencies' => array(…), 'version' => '…'),
 151       *     'interactivity/debug.min.js' => array('dependencies' => array(…), 'version' => '…'),
 152       *     'interactivity-router/index.min.js' => …
 153       */
 154      $assets = include ABSPATH . WPINC . "/assets/script-modules-packages{$suffix}.php";
 155  
 156      foreach ( $assets as $file_name => $script_module_data ) {
 157          /*
 158           * Build the WordPress Script Module ID from the file name.
 159           * Prepend `@wordpress/` and remove extensions and `/index` if present:
 160           *   - interactivity/index.min.js  => @wordpress/interactivity
 161           *   - interactivity/debug.min.js  => @wordpress/interactivity/debug
 162           *   - block-library/query/view.js => @wordpress/block-library/query/view
 163           */
 164          $script_module_id = '@wordpress/' . preg_replace( '~(?:/index)?(?:\.min)?\.js$~D', '', $file_name, 1 );
 165  
 166          switch ( $script_module_id ) {
 167              /*
 168               * Interactivity exposes two entrypoints, "/index" and "/debug".
 169               * "/debug" should replace "/index" in development.
 170               */
 171              case '@wordpress/interactivity/debug':
 172                  if ( ! SCRIPT_DEBUG ) {
 173                      continue 2;
 174                  }
 175                  $script_module_id = '@wordpress/interactivity';
 176                  break;
 177              case '@wordpress/interactivity':
 178                  if ( SCRIPT_DEBUG ) {
 179                      continue 2;
 180                  }
 181                  break;
 182          }
 183  
 184          // The Interactivity API is designed with server-side rendering as its primary goal, so all of its script modules should be loaded with low fetch priority since they should not be needed in the critical rendering path.
 185          $args = array();
 186          if ( str_starts_with( $script_module_id, '@wordpress/interactivity' ) || str_starts_with( $script_module_id, '@wordpress/block-library' ) ) {
 187              $args['fetchpriority'] = 'low';
 188          }
 189  
 190          $path = includes_url( "js/dist/script-modules/{$file_name}" );
 191          wp_register_script_module( $script_module_id, $path, $script_module_data['dependencies'], $script_module_data['version'], $args );
 192      }
 193  }