[ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Dependencies API: WP_Dependencies base class 4 * 5 * @since 2.6.0 6 * 7 * @package WordPress 8 * @subpackage Dependencies 9 */ 10 11 /** 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 28 /** 29 * An array of handles of queued dependencies. 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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Tue Nov 12 01:00:02 2024 | Cross-referenced by PHPXref 0.7.1 |