[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  }