gutenberg / lib / experimental / modules / class-gutenberg-modules.php

class-gutenberg-modules.php in Gutenberg 17.2.1, at lib/experimental/modules/class-gutenberg-modules.php

196 lines 8.0 KB

Raw Download Zip

1	<?php
2	/**
3	* Modules API: Gutenberg_Modules class.
4	*
5	* Native support for ES Modules and Import Maps.
6	*
7	* @package Gutenberg
8	* @subpackage Modules
9	*/
10
11	/**
12	* Gutenberg_Modules class
13	*/
14	class Gutenberg_Modules {
15	/**
16	* An array of registered modules, keyed by module identifier.
17	*
18	* @var array
19	*/
20	private static $registered = array();
21
22	/**
23	* An array of queued modules.
24	*
25	* @var string[]
26	*/
27	private static $enqueued = array();
28
29	/**
30	* Registers the module if no module with that module identifier already
31	* exists.
32	*
33	* @param string $module_identifier The identifier of the module. Should be unique. It will be used in the final import map.
34	* @param string $src Full URL of the module, or path of the script relative to the WordPress root directory.
35	* @param array $dependencies Optional. An array of module identifiers of the static and dynamic dependencies of this module. It can be an indexed array, in which case all the dependencies are static, or it can be an associative array, in which case it has to contain the keys `static` and `dynamic`.
36	* @param string\|bool\|null $version Optional. String specifying module version number. It is added to the URL as a query string for cache busting purposes. If SCRIPT_DEBUG is true, a timestamp is used. If it is set to false, a version number is automatically added equal to current installed WordPress version. If set to null, no version is added.
37	*/
38	public static function register( $module_identifier, $src, $dependencies = array(), $version = false ) {
39	// Register the module if it's not already registered.
40	if ( ! isset( self::$registered[ $module_identifier ] ) ) {
41	$deps = array(
42	'static' => isset( $dependencies['static'] ) \|\| isset( $dependencies['dynamic'] ) ? $dependencies['static'] ?? array() : $dependencies,
43	'dynamic' => isset( $dependencies['dynamic'] ) ? $dependencies['dynamic'] : array(),
44	);
45
46	self::$registered[ $module_identifier ] = array(
47	'src' => $src,
48	'version' => $version,
49	'dependencies' => $deps,
50	);
51	}
52	}
53
54	/**
55	* Enqueues a module in the page.
56	*
57	* @param string $module_identifier The identifier of the module.
58	*/
59	public static function enqueue( $module_identifier ) {
60	// Add the module to the queue if it's not already there.
61	if ( ! in_array( $module_identifier, self::$enqueued, true ) ) {
62	self::$enqueued[] = $module_identifier;
63	}
64	}
65
66	/**
67	* Returns the import map array.
68	*
69	* @return array Associative array with 'imports' key mapping to an array of module identifiers and their respective source strings.
70	*/
71	public static function get_import_map() {
72	$imports = array();
73	foreach ( self::get_dependencies( self::$enqueued, array( 'static', 'dynamic' ) ) as $module_identifier => $module ) {
74	$imports[ $module_identifier ] = $module['src'] . self::get_version_query_string( $module['version'] );
75	}
76	return array( 'imports' => $imports );
77	}
78
79	/**
80	* Prints the import map.
81	*/
82	public static function print_import_map() {
83	$import_map = self::get_import_map();
84	if ( ! empty( $import_map['imports'] ) ) {
85	echo '<script type="importmap">' . wp_json_encode( self::get_import_map(), JSON_HEX_TAG \| JSON_HEX_AMP ) . '</script>';
86	}
87	}
88
89	/**
90	* Prints all the enqueued modules using <script type="module">.
91	*/
92	public static function print_enqueued_modules() {
93	foreach ( self::$enqueued as $module_identifier ) {
94	if ( isset( self::$registered[ $module_identifier ] ) ) {
95	$module = self::$registered[ $module_identifier ];
96	wp_print_script_tag(
97	array(
98	'type' => 'module',
99	'src' => $module['src'] . self::get_version_query_string( $module['version'] ),
100	'id' => $module_identifier,
101	)
102	);
103	}
104	}
105	}
106
107	/**
108	* Prints the link tag with rel="modulepreload" for all the static
109	* dependencies of the enqueued modules.
110	*/
111	public static function print_module_preloads() {
112	foreach ( self::get_dependencies( self::$enqueued, array( 'static' ) ) as $dependency_identifier => $module ) {
113	echo '<link rel="modulepreload" href="' . $module['src'] . self::get_version_query_string( $module['version'] ) . '" id="' . $dependency_identifier . '">';
114	}
115	}
116
117	/**
118	* Gets the module's version. It either returns a timestamp (if SCRIPT_DEBUG
119	* is true), the explicit version of the module if it is set and not false, or
120	* an empty string if none of the above conditions are met.
121	*
122	* @param array $version The version of the module.
123	* @return string A string presenting the version.
124	*/
125	private static function get_version_query_string( $version ) {
126	if ( SCRIPT_DEBUG ) {
127	return '?ver=' . time();
128	} elseif ( false === $version ) {
129	return '?ver=' . get_bloginfo( 'version' );
130	} elseif ( null !== $version ) {
131	return '?ver=' . $version;
132	}
133	return '';
134	}
135
136	/**
137	* Returns all unique static and/or dynamic dependencies for the received modules. It's
138	* recursive, so it will also get the static or dynamic dependencies of the dependencies.
139	*
140	* @param array $module_identifiers The identifiers of the modules to get dependencies for.
141	* @param array $types The type of dependencies to retrieve. It can be `static`, `dynamic` or both.
142	* @return array The array containing the unique dependencies of the modules.
143	*/
144	private static function get_dependencies( $module_identifiers, $types = array( 'static', 'dynamic' ) ) {
145	return array_reduce(
146	$module_identifiers,
147	function ( $dependency_modules, $module_identifier ) use ( $types ) {
148	if ( ! isset( self::$registered[ $module_identifier ] ) ) {
149	return $dependency_modules;
150	}
151
152	$dependencies = array();
153	foreach ( $types as $type ) {
154	$dependencies = array_merge( $dependencies, self::$registered[ $module_identifier ]['dependencies'][ $type ] );
155	}
156	$dependencies = array_unique( $dependencies );
157	$dependency_modules = array_intersect_key( self::$registered, array_flip( $dependencies ) );
158
159	return array_merge( $dependency_modules, $dependency_modules, self::get_dependencies( $dependencies, $types ) );
160	},
161	array()
162	);
163	}
164	}
165
166	/**
167	* Registers a JavaScript module. It will be added to the import map.
168	*
169	* @param string $module_identifier The identifier of the module. Should be unique. It will be used in the final import map.
170	* @param string $src Full URL of the module, or path of the script relative to the WordPress root directory.
171	* @param array $dependencies Optional. An array of module identifiers of the static and dynamic dependencies of this module. It can be an indexed array, in which case all the dependencies are static, or it can be an associative array, in which case it has to contain the keys `static` and `dynamic`.
172	* @param string\|bool\|null $version Optional. String specifying module version number. It is added to the URL as a query string for cache busting purposes. If SCRIPT_DEBUG is true, a timestamp is used. If it is set to false, a version number is automatically added equal to current installed WordPress version. If set to null, no version is added.
173	*/
174	function gutenberg_register_module( $module_identifier, $src, $dependencies = array(), $version = false ) {
175	Gutenberg_Modules::register( $module_identifier, $src, $dependencies, $version );
176	}
177
178	/**
179	* Enqueues a JavaScript module. It will be added to both the import map and a
180	* script tag with the "module" type.
181	*
182	* @param string $module_identifier The identifier of the module. Should be unique. It will be used in the final import map.
183	*/
184	function gutenberg_enqueue_module( $module_identifier ) {
185	Gutenberg_Modules::enqueue( $module_identifier );
186	}
187
188	// Prints the import map in the head tag.
189	add_action( 'wp_head', array( 'Gutenberg_Modules', 'print_import_map' ) );
190
191	// Prints the enqueued modules in the head tag.
192	add_action( 'wp_head', array( 'Gutenberg_Modules', 'print_enqueued_modules' ) );
193
194	// Prints the preloaded modules in the head tag.
195	add_action( 'wp_head', array( 'Gutenberg_Modules', 'print_module_preloads' ) );
196