1 <?php |
1 <?php |
2 /** |
2 /** |
3 * Dependencies API: WP_Dependencies base class |
3 * Dependencies API: WP_Dependencies base class |
4 * |
4 * |
5 * @since 2.6.0 |
5 * This file is deprecated, use 'wp-includes/class-wp-dependencies.php' instead. |
6 * |
6 * |
|
7 * @deprecated 6.1.0 |
7 * @package WordPress |
8 * @package WordPress |
8 * @subpackage Dependencies |
|
9 */ |
9 */ |
10 |
10 |
11 /** |
11 _deprecated_file( basename( __FILE__ ), '6.1.0', WPINC . '/class-wp-dependencies.php' ); |
12 * Core base class extended to register items. |
|
13 * |
|
14 * @since 2.6.0 |
|
15 * |
|
16 * @see _WP_Dependency |
|
17 */ |
|
18 class WP_Dependencies { |
|
19 /** |
|
20 * An array of all registered dependencies keyed by handle. |
|
21 * |
|
22 * @since 2.6.8 |
|
23 * |
|
24 * @var _WP_Dependency[] |
|
25 */ |
|
26 public $registered = array(); |
|
27 |
12 |
28 /** |
13 /** WP_Dependencies class */ |
29 * An array of handles of queued dependencies. |
14 require_once ABSPATH . WPINC . '/class-wp-dependencies.php'; |
30 * |
|
31 * @since 2.6.8 |
|
32 * |
|
33 * @var string[] |
|
34 */ |
|
35 public $queue = array(); |
|
36 |
|
37 /** |
|
38 * An array of handles of dependencies to queue. |
|
39 * |
|
40 * @since 2.6.0 |
|
41 * |
|
42 * @var string[] |
|
43 */ |
|
44 public $to_do = array(); |
|
45 |
|
46 /** |
|
47 * An array of handles of dependencies already queued. |
|
48 * |
|
49 * @since 2.6.0 |
|
50 * |
|
51 * @var string[] |
|
52 */ |
|
53 public $done = array(); |
|
54 |
|
55 /** |
|
56 * An array of additional arguments passed when a handle is registered. |
|
57 * |
|
58 * Arguments are appended to the item query string. |
|
59 * |
|
60 * @since 2.6.0 |
|
61 * |
|
62 * @var array |
|
63 */ |
|
64 public $args = array(); |
|
65 |
|
66 /** |
|
67 * An array of dependency groups to enqueue. |
|
68 * |
|
69 * Each entry is keyed by handle and represents the integer group level or boolean |
|
70 * false if the handle has no group. |
|
71 * |
|
72 * @since 2.8.0 |
|
73 * |
|
74 * @var (int|false)[] |
|
75 */ |
|
76 public $groups = array(); |
|
77 |
|
78 /** |
|
79 * A handle group to enqueue. |
|
80 * |
|
81 * @since 2.8.0 |
|
82 * |
|
83 * @deprecated 4.5.0 |
|
84 * @var int |
|
85 */ |
|
86 public $group = 0; |
|
87 |
|
88 /** |
|
89 * Cached lookup array of flattened queued items and dependencies. |
|
90 * |
|
91 * @since 5.4.0 |
|
92 * |
|
93 * @var array |
|
94 */ |
|
95 private $all_queued_deps; |
|
96 |
|
97 /** |
|
98 * List of assets enqueued before details were registered. |
|
99 * |
|
100 * @since 5.9.0 |
|
101 * |
|
102 * @var array |
|
103 */ |
|
104 private $queued_before_register = array(); |
|
105 |
|
106 /** |
|
107 * Processes the items and dependencies. |
|
108 * |
|
109 * Processes the items passed to it or the queue, and their dependencies. |
|
110 * |
|
111 * @since 2.6.0 |
|
112 * @since 2.8.0 Added the `$group` parameter. |
|
113 * |
|
114 * @param string|string[]|false $handles Optional. Items to be processed: queue (false), |
|
115 * single item (string), or multiple items (array of strings). |
|
116 * Default false. |
|
117 * @param int|false $group Optional. Group level: level (int), no group (false). |
|
118 * @return string[] Array of handles of items that have been processed. |
|
119 */ |
|
120 public function do_items( $handles = false, $group = false ) { |
|
121 /* |
|
122 * If nothing is passed, print the queue. If a string is passed, |
|
123 * print that item. If an array is passed, print those items. |
|
124 */ |
|
125 $handles = false === $handles ? $this->queue : (array) $handles; |
|
126 $this->all_deps( $handles ); |
|
127 |
|
128 foreach ( $this->to_do as $key => $handle ) { |
|
129 if ( ! in_array( $handle, $this->done, true ) && isset( $this->registered[ $handle ] ) ) { |
|
130 /* |
|
131 * Attempt to process the item. If successful, |
|
132 * add the handle to the done array. |
|
133 * |
|
134 * Unset the item from the to_do array. |
|
135 */ |
|
136 if ( $this->do_item( $handle, $group ) ) { |
|
137 $this->done[] = $handle; |
|
138 } |
|
139 |
|
140 unset( $this->to_do[ $key ] ); |
|
141 } |
|
142 } |
|
143 |
|
144 return $this->done; |
|
145 } |
|
146 |
|
147 /** |
|
148 * Processes a dependency. |
|
149 * |
|
150 * @since 2.6.0 |
|
151 * @since 5.5.0 Added the `$group` parameter. |
|
152 * |
|
153 * @param string $handle Name of the item. Should be unique. |
|
154 * @param int|false $group Optional. Group level: level (int), no group (false). |
|
155 * Default false. |
|
156 * @return bool True on success, false if not set. |
|
157 */ |
|
158 public function do_item( $handle, $group = false ) { |
|
159 return isset( $this->registered[ $handle ] ); |
|
160 } |
|
161 |
|
162 /** |
|
163 * Determines dependencies. |
|
164 * |
|
165 * Recursively builds an array of items to process taking |
|
166 * dependencies into account. Does NOT catch infinite loops. |
|
167 * |
|
168 * @since 2.1.0 |
|
169 * @since 2.6.0 Moved from `WP_Scripts`. |
|
170 * @since 2.8.0 Added the `$group` parameter. |
|
171 * |
|
172 * @param string|string[] $handles Item handle (string) or item handles (array of strings). |
|
173 * @param bool $recursion Optional. Internal flag that function is calling itself. |
|
174 * Default false. |
|
175 * @param int|false $group Optional. Group level: level (int), no group (false). |
|
176 * Default false. |
|
177 * @return bool True on success, false on failure. |
|
178 */ |
|
179 public function all_deps( $handles, $recursion = false, $group = false ) { |
|
180 $handles = (array) $handles; |
|
181 if ( ! $handles ) { |
|
182 return false; |
|
183 } |
|
184 |
|
185 foreach ( $handles as $handle ) { |
|
186 $handle_parts = explode( '?', $handle ); |
|
187 $handle = $handle_parts[0]; |
|
188 $queued = in_array( $handle, $this->to_do, true ); |
|
189 |
|
190 if ( in_array( $handle, $this->done, true ) ) { // Already done. |
|
191 continue; |
|
192 } |
|
193 |
|
194 $moved = $this->set_group( $handle, $recursion, $group ); |
|
195 $new_group = $this->groups[ $handle ]; |
|
196 |
|
197 if ( $queued && ! $moved ) { // Already queued and in the right group. |
|
198 continue; |
|
199 } |
|
200 |
|
201 $keep_going = true; |
|
202 if ( ! isset( $this->registered[ $handle ] ) ) { |
|
203 $keep_going = false; // Item doesn't exist. |
|
204 } elseif ( $this->registered[ $handle ]->deps && array_diff( $this->registered[ $handle ]->deps, array_keys( $this->registered ) ) ) { |
|
205 $keep_going = false; // Item requires dependencies that don't exist. |
|
206 } elseif ( $this->registered[ $handle ]->deps && ! $this->all_deps( $this->registered[ $handle ]->deps, true, $new_group ) ) { |
|
207 $keep_going = false; // Item requires dependencies that don't exist. |
|
208 } |
|
209 |
|
210 if ( ! $keep_going ) { // Either item or its dependencies don't exist. |
|
211 if ( $recursion ) { |
|
212 return false; // Abort this branch. |
|
213 } else { |
|
214 continue; // We're at the top level. Move on to the next one. |
|
215 } |
|
216 } |
|
217 |
|
218 if ( $queued ) { // Already grabbed it and its dependencies. |
|
219 continue; |
|
220 } |
|
221 |
|
222 if ( isset( $handle_parts[1] ) ) { |
|
223 $this->args[ $handle ] = $handle_parts[1]; |
|
224 } |
|
225 |
|
226 $this->to_do[] = $handle; |
|
227 } |
|
228 |
|
229 return true; |
|
230 } |
|
231 |
|
232 /** |
|
233 * Register an item. |
|
234 * |
|
235 * Registers the item if no item of that name already exists. |
|
236 * |
|
237 * @since 2.1.0 |
|
238 * @since 2.6.0 Moved from `WP_Scripts`. |
|
239 * |
|
240 * @param string $handle Name of the item. Should be unique. |
|
241 * @param string|bool $src Full URL of the item, or path of the item relative |
|
242 * to the WordPress root directory. If source is set to false, |
|
243 * item is an alias of other items it depends on. |
|
244 * @param string[] $deps Optional. An array of registered item handles this item depends on. |
|
245 * Default empty array. |
|
246 * @param string|bool|null $ver Optional. String specifying item version number, if it has one, |
|
247 * which is added to the URL as a query string for cache busting purposes. |
|
248 * If version is set to false, a version number is automatically added |
|
249 * equal to current installed WordPress version. |
|
250 * If set to null, no version is added. |
|
251 * @param mixed $args Optional. Custom property of the item. NOT the class property $args. |
|
252 * Examples: $media, $in_footer. |
|
253 * @return bool Whether the item has been registered. True on success, false on failure. |
|
254 */ |
|
255 public function add( $handle, $src, $deps = array(), $ver = false, $args = null ) { |
|
256 if ( isset( $this->registered[ $handle ] ) ) { |
|
257 return false; |
|
258 } |
|
259 $this->registered[ $handle ] = new _WP_Dependency( $handle, $src, $deps, $ver, $args ); |
|
260 |
|
261 // If the item was enqueued before the details were registered, enqueue it now. |
|
262 if ( array_key_exists( $handle, $this->queued_before_register ) ) { |
|
263 if ( ! is_null( $this->queued_before_register[ $handle ] ) ) { |
|
264 $this->enqueue( $handle . '?' . $this->queued_before_register[ $handle ] ); |
|
265 } else { |
|
266 $this->enqueue( $handle ); |
|
267 } |
|
268 |
|
269 unset( $this->queued_before_register[ $handle ] ); |
|
270 } |
|
271 |
|
272 return true; |
|
273 } |
|
274 |
|
275 /** |
|
276 * Add extra item data. |
|
277 * |
|
278 * Adds data to a registered item. |
|
279 * |
|
280 * @since 2.6.0 |
|
281 * |
|
282 * @param string $handle Name of the item. Should be unique. |
|
283 * @param string $key The data key. |
|
284 * @param mixed $value The data value. |
|
285 * @return bool True on success, false on failure. |
|
286 */ |
|
287 public function add_data( $handle, $key, $value ) { |
|
288 if ( ! isset( $this->registered[ $handle ] ) ) { |
|
289 return false; |
|
290 } |
|
291 |
|
292 return $this->registered[ $handle ]->add_data( $key, $value ); |
|
293 } |
|
294 |
|
295 /** |
|
296 * Get extra item data. |
|
297 * |
|
298 * Gets data associated with a registered item. |
|
299 * |
|
300 * @since 3.3.0 |
|
301 * |
|
302 * @param string $handle Name of the item. Should be unique. |
|
303 * @param string $key The data key. |
|
304 * @return mixed Extra item data (string), false otherwise. |
|
305 */ |
|
306 public function get_data( $handle, $key ) { |
|
307 if ( ! isset( $this->registered[ $handle ] ) ) { |
|
308 return false; |
|
309 } |
|
310 |
|
311 if ( ! isset( $this->registered[ $handle ]->extra[ $key ] ) ) { |
|
312 return false; |
|
313 } |
|
314 |
|
315 return $this->registered[ $handle ]->extra[ $key ]; |
|
316 } |
|
317 |
|
318 /** |
|
319 * Un-register an item or items. |
|
320 * |
|
321 * @since 2.1.0 |
|
322 * @since 2.6.0 Moved from `WP_Scripts`. |
|
323 * |
|
324 * @param string|string[] $handles Item handle (string) or item handles (array of strings). |
|
325 */ |
|
326 public function remove( $handles ) { |
|
327 foreach ( (array) $handles as $handle ) { |
|
328 unset( $this->registered[ $handle ] ); |
|
329 } |
|
330 } |
|
331 |
|
332 /** |
|
333 * Queue an item or items. |
|
334 * |
|
335 * Decodes handles and arguments, then queues handles and stores |
|
336 * arguments in the class property $args. For example in extending |
|
337 * classes, $args is appended to the item url as a query string. |
|
338 * Note $args is NOT the $args property of items in the $registered array. |
|
339 * |
|
340 * @since 2.1.0 |
|
341 * @since 2.6.0 Moved from `WP_Scripts`. |
|
342 * |
|
343 * @param string|string[] $handles Item handle (string) or item handles (array of strings). |
|
344 */ |
|
345 public function enqueue( $handles ) { |
|
346 foreach ( (array) $handles as $handle ) { |
|
347 $handle = explode( '?', $handle ); |
|
348 |
|
349 if ( ! in_array( $handle[0], $this->queue, true ) && isset( $this->registered[ $handle[0] ] ) ) { |
|
350 $this->queue[] = $handle[0]; |
|
351 |
|
352 // Reset all dependencies so they must be recalculated in recurse_deps(). |
|
353 $this->all_queued_deps = null; |
|
354 |
|
355 if ( isset( $handle[1] ) ) { |
|
356 $this->args[ $handle[0] ] = $handle[1]; |
|
357 } |
|
358 } elseif ( ! isset( $this->registered[ $handle[0] ] ) ) { |
|
359 $this->queued_before_register[ $handle[0] ] = null; // $args |
|
360 |
|
361 if ( isset( $handle[1] ) ) { |
|
362 $this->queued_before_register[ $handle[0] ] = $handle[1]; |
|
363 } |
|
364 } |
|
365 } |
|
366 } |
|
367 |
|
368 /** |
|
369 * Dequeue an item or items. |
|
370 * |
|
371 * Decodes handles and arguments, then dequeues handles |
|
372 * and removes arguments from the class property $args. |
|
373 * |
|
374 * @since 2.1.0 |
|
375 * @since 2.6.0 Moved from `WP_Scripts`. |
|
376 * |
|
377 * @param string|string[] $handles Item handle (string) or item handles (array of strings). |
|
378 */ |
|
379 public function dequeue( $handles ) { |
|
380 foreach ( (array) $handles as $handle ) { |
|
381 $handle = explode( '?', $handle ); |
|
382 $key = array_search( $handle[0], $this->queue, true ); |
|
383 |
|
384 if ( false !== $key ) { |
|
385 // Reset all dependencies so they must be recalculated in recurse_deps(). |
|
386 $this->all_queued_deps = null; |
|
387 |
|
388 unset( $this->queue[ $key ] ); |
|
389 unset( $this->args[ $handle[0] ] ); |
|
390 } elseif ( array_key_exists( $handle[0], $this->queued_before_register ) ) { |
|
391 unset( $this->queued_before_register[ $handle[0] ] ); |
|
392 } |
|
393 } |
|
394 } |
|
395 |
|
396 /** |
|
397 * Recursively search the passed dependency tree for a handle. |
|
398 * |
|
399 * @since 4.0.0 |
|
400 * |
|
401 * @param string[] $queue An array of queued _WP_Dependency handles. |
|
402 * @param string $handle Name of the item. Should be unique. |
|
403 * @return bool Whether the handle is found after recursively searching the dependency tree. |
|
404 */ |
|
405 protected function recurse_deps( $queue, $handle ) { |
|
406 if ( isset( $this->all_queued_deps ) ) { |
|
407 return isset( $this->all_queued_deps[ $handle ] ); |
|
408 } |
|
409 |
|
410 $all_deps = array_fill_keys( $queue, true ); |
|
411 $queues = array(); |
|
412 $done = array(); |
|
413 |
|
414 while ( $queue ) { |
|
415 foreach ( $queue as $queued ) { |
|
416 if ( ! isset( $done[ $queued ] ) && isset( $this->registered[ $queued ] ) ) { |
|
417 $deps = $this->registered[ $queued ]->deps; |
|
418 if ( $deps ) { |
|
419 $all_deps += array_fill_keys( $deps, true ); |
|
420 array_push( $queues, $deps ); |
|
421 } |
|
422 $done[ $queued ] = true; |
|
423 } |
|
424 } |
|
425 $queue = array_pop( $queues ); |
|
426 } |
|
427 |
|
428 $this->all_queued_deps = $all_deps; |
|
429 |
|
430 return isset( $this->all_queued_deps[ $handle ] ); |
|
431 } |
|
432 |
|
433 /** |
|
434 * Query the list for an item. |
|
435 * |
|
436 * @since 2.1.0 |
|
437 * @since 2.6.0 Moved from `WP_Scripts`. |
|
438 * |
|
439 * @param string $handle Name of the item. Should be unique. |
|
440 * @param string $status Optional. Status of the item to query. Default 'registered'. |
|
441 * @return bool|_WP_Dependency Found, or object Item data. |
|
442 */ |
|
443 public function query( $handle, $status = 'registered' ) { |
|
444 switch ( $status ) { |
|
445 case 'registered': |
|
446 case 'scripts': // Back compat. |
|
447 if ( isset( $this->registered[ $handle ] ) ) { |
|
448 return $this->registered[ $handle ]; |
|
449 } |
|
450 return false; |
|
451 |
|
452 case 'enqueued': |
|
453 case 'queue': // Back compat. |
|
454 if ( in_array( $handle, $this->queue, true ) ) { |
|
455 return true; |
|
456 } |
|
457 return $this->recurse_deps( $this->queue, $handle ); |
|
458 |
|
459 case 'to_do': |
|
460 case 'to_print': // Back compat. |
|
461 return in_array( $handle, $this->to_do, true ); |
|
462 |
|
463 case 'done': |
|
464 case 'printed': // Back compat. |
|
465 return in_array( $handle, $this->done, true ); |
|
466 } |
|
467 |
|
468 return false; |
|
469 } |
|
470 |
|
471 /** |
|
472 * Set item group, unless already in a lower group. |
|
473 * |
|
474 * @since 2.8.0 |
|
475 * |
|
476 * @param string $handle Name of the item. Should be unique. |
|
477 * @param bool $recursion Internal flag that calling function was called recursively. |
|
478 * @param int|false $group Group level: level (int), no group (false). |
|
479 * @return bool Not already in the group or a lower group. |
|
480 */ |
|
481 public function set_group( $handle, $recursion, $group ) { |
|
482 $group = (int) $group; |
|
483 |
|
484 if ( isset( $this->groups[ $handle ] ) && $this->groups[ $handle ] <= $group ) { |
|
485 return false; |
|
486 } |
|
487 |
|
488 $this->groups[ $handle ] = $group; |
|
489 |
|
490 return true; |
|
491 } |
|
492 |
|
493 } |
|