Skip to content

Commit ed88ebb

Browse files
ockhamockham
committed
JavaScript: Add new Modules API.
This changeset adds a new API for WordPress, designed to work with native ES Modules and Import Maps. It introduces functions such as `wp_register_module`, and `wp_enqueue_module`. The API aims to provide a familiar experience to the existing `WP_Scripts` class, offering similar functionality. However, **it's not intended to duplicate the exact functionality of `WP_Scripts`**; rather, it is carefully tailored to address the specific needs and capabilities of ES modules. For this initial version, **the current proposal is intentionally simplistic**, covering only the essential features needed to work with ES modules. Other enhancements and optimizations can be added later as the community identifies additional requirements and use cases. == Differences Between WP_Script_Modules and WP_Scripts === Dependency Specification With `WP_Script_Modules`, the array of dependencies supports not only strings but also arrays that include the dependency import type (`static` or `dynamic`). This design choice allows for future extensions of dependency properties, such as adding a `version` property to support "scopes" within import maps. === Module Identifier Instead of a handle, `WP_Script_Modules` utilizes the module identifier, aligning with the module identifiers used in JavaScript files and import maps. === Deregistration There is no equivalent of `wp_deregister_script` at this stage. == API === `wp_register_module( $module_identifier, $src, $deps, $version )` Registers a module. {{{ // Registers a module with dependencies and versioning. wp_register_module( 'my-module', '/path/to/my-module.js', array( 'static-dependency-1', 'static-dependency-2' ), '1.2.3' ); }}} {{{ // my-module.js import { ... } from 'static-dependency-1'; import { ... } from 'static-dependency-2'; // ... }}} {{{ // Registers a module with a dynamic dependency. wp_register_module( 'my-module', '/path/to/my-module.js', array( 'static-dependency', array( 'id' => 'dynamic-dependency', 'import' => 'dynamic' ), ) ); }}} {{{ // my-module.js import { ... } from 'static-dependency'; // ... const dynamicModule = await import('dynamic-dependency'); }}} === `wp_enqueue_module( $module_identifier, $src, $deps, $version )` Enqueues a module. If a source is provided, it will also register the module. {{{ wp_enqueue_module( 'my-module' ); }}} === `wp_dequeue_module( $module_identifier )` Dequeues a module. {{{ wp_dequeue_module( 'my-module' ); }}} == Output - When modules are enqueued, they are printed within script tags containing `type="module"` attributes. - Additionally, static dependencies of enqueued modules utilize `link` tags with `rel="modulepreload"` attributes. - Lastly, an import map is generated and inserted using a `<script type="importmap">` tag. {{{ <script type="module" src="/path/to/my-module.js" id="my-module"></script> <link rel="modulepreload" href="/path/to/static-dependency.js" id="static-dependency" /> <script type="importmap"> { "imports": { "static-dependency": "/path/to/static-dependency.js", "dynamic-dependency": "/path/to/dynamic-dependency.js" } } </script> }}} == Import Map Polyfill Requirement Even though all major browsers already support import maps, an import map polyfill is required until the percentage of users using old browser versions without import map support drops significantly. This work is ongoing and will be added once it's ready. Progress is tracked in #60232. Props luisherranz, idad5, costdev, neffff, joemcgill, jorbin, swissspidy, jonsurrell, flixos90, gziolo, westonruter. Fixes #56313. git-svn-id: https://develop.svn.wordpress.org/trunk@57269 602fd350-edb4-49c9-b593-d223f7449a82
1 parent fd42519 commit ed88ebb

4 files changed

Lines changed: 1139 additions & 0 deletions

File tree

‎src/wp-includes/class-wp-script-modules.php‎

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,352 @@
1+
<?php
2+
/**
3+
* Modules API: WP_Script_Modules class.
4+
*
5+
* Native support for ES Modules and Import Maps.
6+
*
7+
* @package WordPress
8+
* @subpackage Script Modules
9+
*/
10+
11+
/**
12+
* Core class used to register modules.
13+
*
14+
* @since 6.5.0
15+
*/
16+
class WP_Script_Modules {
17+
/**
18+
* Holds the registered modules, keyed by module identifier.
19+
*
20+
* @since 6.5.0
21+
* @var array
22+
*/
23+
private $registered = array();
24+
25+
/**
26+
* Holds the module identifiers that were enqueued before registered.
27+
*
28+
* @since 6.5.0
29+
* @var array
30+
*/
31+
private $enqueued_before_registered = array();
32+
33+
/**
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 ] ) ) {
67+
$dependencies = array();
68+
foreach ( $deps as $dependency ) {
69+
if ( is_array( $dependency ) ) {
70+
if ( ! isset( $dependency['id'] ) ) {
71+
_doing_it_wrong( __METHOD__, __( 'Missing required id key in entry among dependencies array.' ), '6.5.0' );
72+
continue;
73+
}
74+
$dependencies[] = array(
75+
'id' => $dependency['id'],
76+
'import' => isset( $dependency['import'] ) && 'dynamic' === $dependency['import'] ? 'dynamic' : 'static',
77+
);
78+
} elseif ( is_string( $dependency ) ) {
79+
$dependencies[] = array(
80+
'id' => $dependency,
81+
'import' => 'static',
82+
);
83+
} else {
84+
_doing_it_wrong( __METHOD__, __( 'Entries in dependencies array must be either strings or arrays with an id key.' ), '6.5.0' );
85+
}
86+
}
87+
88+
$this->registered[ $module_id ] = array(
89+
'src' => $src,
90+
'version' => $version,
91+
'enqueue' => isset( $this->enqueued_before_registered[ $module_id ] ),
92+
'dependencies' => $dependencies,
93+
'enqueued' => false,
94+
'preloaded' => false,
95+
);
96+
}
97+
}
98+
99+
/**
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;
140+
} elseif ( $src ) {
141+
$this->register( $module_id, $src, $deps, $version );
142+
$this->registered[ $module_id ]['enqueue'] = true;
143+
} 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.
176+
*
177+
* 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.
179+
*
180+
* @since 6.5.0
181+
*/
182+
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' ) );
187+
add_action( 'wp_footer', array( $this, 'print_import_map' ) );
188+
}
189+
190+
/**
191+
* Prints the enqueued modules using script tags with type="module"
192+
* attributes.
193+
*
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'] ) {
202+
// Mark it as enqueued so it doesn't get enqueued again.
203+
$this->registered[ $module_id ]['enqueued'] = true;
204+
205+
wp_print_script_tag(
206+
array(
207+
'type' => 'module',
208+
'src' => $this->get_versioned_src( $module ),
209+
'id' => $module_id . '-js-module',
210+
)
211+
);
212+
}
213+
}
214+
}
215+
216+
/**
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 ) {
228+
// Don't preload if it's marked for enqueue or has already been preloaded.
229+
if ( true !== $module['enqueue'] && false === $module['preloaded'] ) {
230+
// Mark it as preloaded so it doesn't get preloaded again.
231+
$this->registered[ $module_id ]['preloaded'] = true;
232+
233+
echo sprintf(
234+
'<link rel="modulepreload" href="%s" id="%s">',
235+
esc_url( $this->get_versioned_src( $module ) ),
236+
esc_attr( $module_id . '-js-modulepreload' )
237+
);
238+
}
239+
}
240+
}
241+
242+
/**
243+
* Prints the import map using a script tag with a type="importmap" attribute.
244+
*
245+
* @since 6.5.0
246+
*/
247+
public function print_import_map() {
248+
$import_map = $this->get_import_map();
249+
if ( ! empty( $import_map['imports'] ) ) {
250+
wp_print_inline_script_tag(
251+
wp_json_encode( $import_map, JSON_HEX_TAG | JSON_HEX_AMP ),
252+
array(
253+
'type' => 'importmap',
254+
'id' => 'wp-importmap',
255+
)
256+
);
257+
}
258+
}
259+
260+
/**
261+
* Returns the import map array.
262+
*
263+
* @since 6.5.0
264+
*
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() {
269+
$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 );
272+
}
273+
return array( 'imports' => $imports );
274+
}
275+
276+
/**
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() {
284+
$enqueued = array();
285+
foreach ( $this->registered as $module_id => $module ) {
286+
if ( true === $module['enqueue'] ) {
287+
$enqueued[ $module_id ] = $module;
288+
}
289+
}
290+
return $enqueued;
291+
}
292+
293+
/**
294+
* Retrieves all the dependencies for the given module identifiers, filtered
295+
* by import types.
296+
*
297+
* It will consolidate an array containing a set of unique dependencies based
298+
* on the requested import types: 'static', 'dynamic', or both. This method is
299+
* recursive and also retrieves dependencies of the dependencies.
300+
*
301+
* @since 6.5.0
302+
*
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' ) ) {
309+
return array_reduce(
310+
$module_ids,
311+
function ( $dependency_modules, $module_id ) use ( $import_types ) {
312+
$dependencies = array();
313+
foreach ( $this->registered[ $module_id ]['dependencies'] as $dependency ) {
314+
if (
315+
in_array( $dependency['import'], $import_types, true ) &&
316+
isset( $this->registered[ $dependency['id'] ] ) &&
317+
! isset( $dependency_modules[ $dependency['id'] ] )
318+
) {
319+
$dependencies[ $dependency['id'] ] = $this->registered[ $dependency['id'] ];
320+
}
321+
}
322+
return array_merge( $dependency_modules, $dependencies, $this->get_dependencies( array_keys( $dependencies ), $import_types ) );
323+
},
324+
array()
325+
);
326+
}
327+
328+
/**
329+
* Gets the versioned URL for a module src.
330+
*
331+
* If $version is set to false, the version number is the currently installed
332+
* WordPress version. If $version is set to null, no version is added.
333+
* Otherwise, the string passed in $version is used.
334+
*
335+
* @since 6.5.0
336+
*
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 ) {
341+
$args = array();
342+
if ( false === $module['version'] ) {
343+
$args['ver'] = get_bloginfo( 'version' );
344+
} elseif ( null !== $module['version'] ) {
345+
$args['ver'] = $module['version'];
346+
}
347+
if ( $args ) {
348+
return add_query_arg( $args, $module['src'] );
349+
}
350+
return $module['src'];
351+
}
352+
}

0 commit comments

Comments
 (0)