wp-includes/class.wp-dependencies.php

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