[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       * Processes the items and dependencies.
  80       *
  81       * Processes the items passed to it or the queue, and their dependencies.
  82       *
  83       * @since 2.6.0
  84       * @since 2.8.0 Added the `$group` parameter.
  85       *
  86       * @param mixed     $handles Optional. Items to be processed: Process queue (false), process item (string), process items (array of strings).
  87       * @param int|false $group   Optional. Group level: level (int), no groups (false).
  88       * @return string[] Array of handles of items that have been processed.
  89       */
  90  	public function do_items( $handles = false, $group = false ) {
  91          /*
  92           * If nothing is passed, print the queue. If a string is passed,
  93           * print that item. If an array is passed, print those items.
  94           */
  95          $handles = false === $handles ? $this->queue : (array) $handles;
  96          $this->all_deps( $handles );
  97  
  98          foreach ( $this->to_do as $key => $handle ) {
  99              if ( ! in_array( $handle, $this->done, true ) && isset( $this->registered[ $handle ] ) ) {
 100                  /*
 101                   * Attempt to process the item. If successful,
 102                   * add the handle to the done array.
 103                   *
 104                   * Unset the item from the to_do array.
 105                   */
 106                  if ( $this->do_item( $handle, $group ) ) {
 107                      $this->done[] = $handle;
 108                  }
 109  
 110                  unset( $this->to_do[ $key ] );
 111              }
 112          }
 113  
 114          return $this->done;
 115      }
 116  
 117      /**
 118       * Processes a dependency.
 119       *
 120       * @since 2.6.0
 121       *
 122       * @param string $handle Name of the item. Should be unique.
 123       * @return bool True on success, false if not set.
 124       */
 125  	public function do_item( $handle ) {
 126          return isset( $this->registered[ $handle ] );
 127      }
 128  
 129      /**
 130       * Determines dependencies.
 131       *
 132       * Recursively builds an array of items to process taking
 133       * dependencies into account. Does NOT catch infinite loops.
 134       *
 135       * @since 2.1.0
 136       * @since 2.6.0 Moved from `WP_Scripts`.
 137       * @since 2.8.0 Added the `$group` parameter.
 138       *
 139       * @param string|string[] $handles   Item handle and argument (string) or item handles and arguments (array of strings).
 140       * @param bool            $recursion Internal flag that function is calling itself.
 141       * @param int|false       $group     Group level: (int) level, (false) no groups.
 142       * @return bool True on success, false on failure.
 143       */
 144  	public function all_deps( $handles, $recursion = false, $group = false ) {
 145          $handles = (array) $handles;
 146          if ( ! $handles ) {
 147              return false;
 148          }
 149  
 150          foreach ( $handles as $handle ) {
 151              $handle_parts = explode( '?', $handle );
 152              $handle       = $handle_parts[0];
 153              $queued       = in_array( $handle, $this->to_do, true );
 154  
 155              if ( in_array( $handle, $this->done, true ) ) { // Already done.
 156                  continue;
 157              }
 158  
 159              $moved     = $this->set_group( $handle, $recursion, $group );
 160              $new_group = $this->groups[ $handle ];
 161  
 162              if ( $queued && ! $moved ) { // Already queued and in the right group.
 163                  continue;
 164              }
 165  
 166              $keep_going = true;
 167              if ( ! isset( $this->registered[ $handle ] ) ) {
 168                  $keep_going = false; // Item doesn't exist.
 169              } elseif ( $this->registered[ $handle ]->deps && array_diff( $this->registered[ $handle ]->deps, array_keys( $this->registered ) ) ) {
 170                  $keep_going = false; // Item requires dependencies that don't exist.
 171              } elseif ( $this->registered[ $handle ]->deps && ! $this->all_deps( $this->registered[ $handle ]->deps, true, $new_group ) ) {
 172                  $keep_going = false; // Item requires dependencies that don't exist.
 173              }
 174  
 175              if ( ! $keep_going ) { // Either item or its dependencies don't exist.
 176                  if ( $recursion ) {
 177                      return false; // Abort this branch.
 178                  } else {
 179                      continue; // We're at the top level. Move on to the next one.
 180                  }
 181              }
 182  
 183              if ( $queued ) { // Already grabbed it and its dependencies.
 184                  continue;
 185              }
 186  
 187              if ( isset( $handle_parts[1] ) ) {
 188                  $this->args[ $handle ] = $handle_parts[1];
 189              }
 190  
 191              $this->to_do[] = $handle;
 192          }
 193  
 194          return true;
 195      }
 196  
 197      /**
 198       * Register an item.
 199       *
 200       * Registers the item if no item of that name already exists.
 201       *
 202       * @since 2.1.0
 203       * @since 2.6.0 Moved from `WP_Scripts`.
 204       *
 205       * @param string           $handle Name of the item. Should be unique.
 206       * @param string|bool      $src    Full URL of the item, or path of the item relative to the WordPress root directory.
 207       *                                 If source is set to false, item is an alias of other items it depends on.
 208       * @param string[]         $deps   Optional. An array of registered item handles this item depends on. Default empty array.
 209       * @param string|bool|null $ver    Optional. String specifying item version number, if it has one, which is added to the URL
 210       *                                 as a query string for cache busting purposes. If version is set to false, a version
 211       *                                 number is automatically added equal to current installed WordPress version.
 212       *                                 If set to null, no version is added.
 213       * @param mixed            $args   Optional. Custom property of the item. NOT the class property $args. Examples: $media, $in_footer.
 214       * @return bool Whether the item has been registered. True on success, false on failure.
 215       */
 216  	public function add( $handle, $src, $deps = array(), $ver = false, $args = null ) {
 217          if ( isset( $this->registered[ $handle ] ) ) {
 218              return false;
 219          }
 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       * @since 2.6.0
 230       *
 231       * @param string $handle Name of the item. Should be unique.
 232       * @param string $key    The data key.
 233       * @param mixed  $value  The data value.
 234       * @return bool True on success, false on failure.
 235       */
 236  	public function add_data( $handle, $key, $value ) {
 237          if ( ! isset( $this->registered[ $handle ] ) ) {
 238              return false;
 239          }
 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       * @since 3.3.0
 250       *
 251       * @param string $handle Name of the item. Should be unique.
 252       * @param string $key    The data key.
 253       * @return mixed Extra item data (string), false otherwise.
 254       */
 255  	public function get_data( $handle, $key ) {
 256          if ( ! isset( $this->registered[ $handle ] ) ) {
 257              return false;
 258          }
 259  
 260          if ( ! isset( $this->registered[ $handle ]->extra[ $key ] ) ) {
 261              return false;
 262          }
 263  
 264          return $this->registered[ $handle ]->extra[ $key ];
 265      }
 266  
 267      /**
 268       * Un-register an item or items.
 269       *
 270       * @since 2.1.0
 271       * @since 2.6.0 Moved from `WP_Scripts`.
 272       *
 273       * @param string|string[] $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      /**
 283       * Queue an item or items.
 284       *
 285       * Decodes handles and arguments, then queues handles and stores
 286       * arguments in the class property $args. For example in extending
 287       * classes, $args is appended to the item url as a query string.
 288       * Note $args is NOT the $args property of items in the $registered array.
 289       *
 290       * @since 2.1.0
 291       * @since 2.6.0 Moved from `WP_Scripts`.
 292       *
 293       * @param string|string[] $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      /**
 308       * Dequeue an item or items.
 309       *
 310       * Decodes handles and arguments, then dequeues handles
 311       * and removes arguments from the class property $args.
 312       *
 313       * @since 2.1.0
 314       * @since 2.6.0 Moved from `WP_Scripts`.
 315       *
 316       * @param string|string[] $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 string[] $queue  An array of queued _WP_Dependency handles.
 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       * @since 2.1.0
 358       * @since 2.6.0 Moved from `WP_Scripts`.
 359       *
 360       * @param string $handle Name of the item. Should be unique.
 361       * @param string $list   Property name of list array.
 362       * @return bool|_WP_Dependency Found, or object Item data.
 363       */
 364  	public function query( $handle, $list = 'registered' ) {
 365          switch ( $list ) {
 366              case 'registered':
 367              case 'scripts': // Back compat.
 368                  if ( isset( $this->registered[ $handle ] ) ) {
 369                      return $this->registered[ $handle ];
 370                  }
 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       * @since 2.8.0
 395       *
 396       * @param string $handle    Name of the item. Should be unique.
 397       * @param bool   $recursion Internal flag that calling function was called recursively.
 398       * @param mixed  $group     Group level.
 399       * @return bool Not already in the group or a lower group
 400       */
 401  	public function set_group( $handle, $recursion, $group ) {
 402          $group = (int) $group;
 403  
 404          if ( isset( $this->groups[ $handle ] ) && $this->groups[ $handle ] <= $group ) {
 405              return false;
 406          }
 407  
 408          $this->groups[ $handle ] = $group;
 409  
 410          return true;
 411      }
 412  
 413  }