| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[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<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 { 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<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 { 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 * Overrides the text domain and path used to load translations for a script module. 143 * 144 * Translations for script modules are loaded automatically from the default 145 * text domain and language directory. Use this function only when a module's 146 * text domain differs from `'default'` or when translation files live outside 147 * the standard location, for example plugin modules using their own text domain. 148 * 149 * @since 7.0.0 150 * 151 * @see WP_Script_Modules::set_translations() 152 * 153 * @param string $id The identifier of the script module. 154 * @param string $domain Optional. Text domain. Default 'default'. 155 * @param string $path Optional. The full file path to the directory containing translation files. 156 * @return bool True if the text domain was registered, false if the module is not registered. 157 */ 158 function wp_set_script_module_translations( string $id, string $domain = 'default', string $path = '' ): bool { 159 return wp_script_modules()->set_translations( $id, $domain, $path ); 160 } 161 162 /** 163 * Registers all the default WordPress Script Modules. 164 * 165 * @since 6.7.0 166 */ 167 function wp_default_script_modules() { 168 $suffix = defined( 'WP_RUN_CORE_TESTS' ) ? '.min' : wp_scripts_get_suffix(); 169 170 /* 171 * Expects multidimensional array like: 172 * 173 * 'interactivity/index.js' => array('dependencies' => array(…), 'version' => '…'), 174 * 'interactivity-router/index.js' => array('dependencies' => array(…), 'version' => '…'), 175 * 'block-library/navigation/view.js' => … 176 */ 177 $assets_file = ABSPATH . WPINC . '/assets/script-modules-packages.php'; 178 $assets = file_exists( $assets_file ) ? include $assets_file : array(); 179 180 foreach ( $assets as $file_name => $script_module_data ) { 181 /* 182 * Build the WordPress Script Module ID from the file name. 183 * Prepend `@wordpress/` and remove extensions and `/index` if present: 184 * - interactivity/index.min.js => @wordpress/interactivity 185 * - interactivity-router/index.min.js => @wordpress/interactivity-router 186 * - block-library/navigation/view.js => @wordpress/block-library/navigation/view 187 */ 188 $script_module_id = '@wordpress/' . preg_replace( '~(?:/index)?(?:\.min)?\.js$~D', '', $file_name, 1 ); 189 190 /* 191 * The Interactivity API is designed with server-side rendering as its primary goal, so all of its script modules 192 * should be loaded with low fetchpriority and printed in the footer since they should not be needed in the 193 * critical rendering path. Also, the @wordpress/a11y script module is intended to be used as a dynamic import 194 * dependency, in which case the fetchpriority is irrelevant. See <https://make.wordpress.org/core/2024/10/14/updates-to-script-modules-in-6-7/>. 195 * However, in case it is added as a static import dependency, the fetchpriority is explicitly set to be 'low' 196 * since the module should not be involved in the critical rendering path, and if it is, its fetchpriority will 197 * be bumped to match the fetchpriority of the dependent script. 198 */ 199 $args = array(); 200 if ( 201 str_starts_with( $script_module_id, '@wordpress/interactivity' ) || 202 str_starts_with( $script_module_id, '@wordpress/block-library' ) || 203 '@wordpress/a11y' === $script_module_id 204 ) { 205 $args['fetchpriority'] = 'low'; 206 $args['in_footer'] = true; 207 } 208 209 // Marks all Core blocks as compatible with client-side navigation. 210 if ( str_starts_with( $script_module_id, '@wordpress/block-library' ) ) { 211 wp_interactivity()->add_client_navigation_support_to_script_module( $script_module_id ); 212 } 213 214 // VIPS files are always minified — the non-minified versions are not 215 // shipped because they are ~10MB of inlined WASM with no debugging value. 216 if ( str_starts_with( $file_name, 'vips/' ) ) { 217 $file_name = str_replace( '.js', '.min.js', $file_name ); 218 } elseif ( '' !== $suffix ) { 219 $file_name = str_replace( '.js', $suffix . '.js', $file_name ); 220 } 221 222 $path = includes_url( "js/dist/script-modules/{$file_name}" ); 223 $module_deps = $script_module_data['module_dependencies'] ?? array(); 224 wp_register_script_module( $script_module_id, $path, $module_deps, $script_module_data['version'], $args ); 225 } 226 } 227 228 /** 229 * Enqueues script modules required by the block editor. 230 * 231 * @since 6.9.0 232 */ 233 function wp_enqueue_block_editor_script_modules() { 234 /* 235 * Enqueue the LaTeX to MathML loader for the math block editor. 236 * The loader dynamically imports the main LaTeX to MathML module when needed. 237 */ 238 wp_enqueue_script_module( '@wordpress/latex-to-mathml/loader' ); 239 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Mon Jun 15 08:20:09 2026 | Cross-referenced by PHPXref |