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