[ Index ]

WordPress 5.4.1

[ Index ]     [ Classes ]     [ Functions ]     [ Variables ]     [ Constants ]     [ Statistics ]    

title

Body

[close]

/wp-includes/ -> class.wp-dependencies.php (source)

   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       *
 132       * @param string $handle Name of the item. Should be unique.
 133       * @return bool True on success, false if not set.
 134       */
 135  	public function do_item( $handle ) {
 136          return isset( $this->registered[ $handle ] );
 137      }
 138  
 139      /**
 140       * Determines dependencies.
 141       *
 142       * Recursively builds an array of items to process taking
 143       * dependencies into account. Does NOT catch infinite loops.
 144       *
 145       * @since 2.1.0
 146       * @since 2.6.0 Moved from `WP_Scripts`.
 147       * @since 2.8.0 Added the `$group` parameter.
 148       *
 149       * @param string|string[] $handles   Item handle (string) or item handles (array of strings).
 150       * @param bool            $recursion Optional. Internal flag that function is calling itself.
 151       *                                   Default false.
 152       * @param int|false       $group     Optional. Group level: level (int), no groups (false).
 153       *                                   Default false.
 154       * @return bool True on success, false on failure.
 155       */
 156  	public function all_deps( $handles, $recursion = false, $group = false ) {
 157          $handles = (array) $handles;
 158          if ( ! $handles ) {
 159              return false;
 160          }
 161  
 162          foreach ( $handles as $handle ) {
 163              $handle_parts = explode( '?', $handle );
 164              $handle       = $handle_parts[0];
 165              $queued       = in_array( $handle, $this->to_do, true );
 166  
 167              if ( in_array( $handle, $this->done, true ) ) { // Already done.
 168                  continue;
 169              }
 170  
 171              $moved     = $this->set_group( $handle, $recursion, $group );
 172              $new_group = $this->groups[ $handle ];
 173  
 174              if ( $queued && ! $moved ) { // Already queued and in the right group.
 175                  continue;
 176              }
 177  
 178              $keep_going = true;
 179              if ( ! isset( $this->registered[ $handle ] ) ) {
 180                  $keep_going = false; // Item doesn't exist.
 181              } elseif ( $this->registered[ $handle ]->deps && array_diff( $this->registered[ $handle ]->deps, array_keys( $this->registered ) ) ) {
 182                  $keep_going = false; // Item requires dependencies that don't exist.
 183              } elseif ( $this->registered[ $handle ]->deps && ! $this->all_deps( $this->registered[ $handle ]->deps, true, $new_group ) ) {
 184                  $keep_going = false; // Item requires dependencies that don't exist.
 185              }
 186  
 187              if ( ! $keep_going ) { // Either item or its dependencies don't exist.
 188                  if ( $recursion ) {
 189                      return false; // Abort this branch.
 190                  } else {
 191                      continue; // We're at the top level. Move on to the next one.
 192                  }
 193              }
 194  
 195              if ( $queued ) { // Already grabbed it and its dependencies.
 196                  continue;
 197              }
 198  
 199              if ( isset( $handle_parts[1] ) ) {
 200                  $this->args[ $handle ] = $handle_parts[1];
 201              }
 202  
 203              $this->to_do[] = $handle;
 204          }
 205  
 206          return true;
 207      }
 208  
 209      /**
 210       * Register an item.
 211       *
 212       * Registers the item if no item of that name already exists.
 213       *
 214       * @since 2.1.0
 215       * @since 2.6.0 Moved from `WP_Scripts`.
 216       *
 217       * @param string           $handle Name of the item. Should be unique.
 218       * @param string|bool      $src    Full URL of the item, or path of the item relative
 219       *                                 to the WordPress root directory. If source is set to false,
 220       *                                 item is an alias of other items it depends on.
 221       * @param string[]         $deps   Optional. An array of registered item handles this item depends on.
 222       *                                 Default empty array.
 223       * @param string|bool|null $ver    Optional. String specifying item version number, if it has one,
 224       *                                 which is added to the URL as a query string for cache busting purposes.
 225       *                                 If version is set to false, a version number is automatically added
 226       *                                 equal to current installed WordPress version.
 227       *                                 If set to null, no version is added.
 228       * @param mixed            $args   Optional. Custom property of the item. NOT the class property $args.
 229       *                                 Examples: $media, $in_footer.
 230       * @return bool Whether the item has been registered. True on success, false on failure.
 231       */
 232  	public function add( $handle, $src, $deps = array(), $ver = false, $args = null ) {
 233          if ( isset( $this->registered[ $handle ] ) ) {
 234              return false;
 235          }
 236          $this->registered[ $handle ] = new _WP_Dependency( $handle, $src, $deps, $ver, $args );
 237          return true;
 238      }
 239  
 240      /**
 241       * Add extra item data.
 242       *
 243       * Adds data to a registered item.
 244       *
 245       * @since 2.6.0
 246       *
 247       * @param string $handle Name of the item. Should be unique.
 248       * @param string $key    The data key.
 249       * @param mixed  $value  The data value.
 250       * @return bool True on success, false on failure.
 251       */
 252  	public function add_data( $handle, $key, $value ) {
 253          if ( ! isset( $this->registered[ $handle ] ) ) {
 254              return false;
 255          }
 256  
 257          return $this->registered[ $handle ]->add_data( $key, $value );
 258      }
 259  
 260      /**
 261       * Get extra item data.
 262       *
 263       * Gets data associated with a registered item.
 264       *
 265       * @since 3.3.0
 266       *
 267       * @param string $handle Name of the item. Should be unique.
 268       * @param string $key    The data key.
 269       * @return mixed Extra item data (string), false otherwise.
 270       */
 271  	public function get_data( $handle, $key ) {
 272          if ( ! isset( $this->registered[ $handle ] ) ) {
 273              return false;
 274          }
 275  
 276          if ( ! isset( $this->registered[ $handle ]->extra[ $key ] ) ) {
 277              return false;
 278          }
 279  
 280          return $this->registered[ $handle ]->extra[ $key ];
 281      }
 282  
 283      /**
 284       * Un-register an item or items.
 285       *
 286       * @since 2.1.0
 287       * @since 2.6.0 Moved from `WP_Scripts`.
 288       *
 289       * @param string|string[] $handles Item handle (string) or item handles (array of strings).
 290       */
 291  	public function remove( $handles ) {
 292          foreach ( (array) $handles as $handle ) {
 293              unset( $this->registered[ $handle ] );
 294          }
 295      }
 296  
 297      /**
 298       * Queue an item or items.
 299       *
 300       * Decodes handles and arguments, then queues handles and stores
 301       * arguments in the class property $args. For example in extending
 302       * classes, $args is appended to the item url as a query string.
 303       * Note $args is NOT the $args property of items in the $registered array.
 304       *
 305       * @since 2.1.0
 306       * @since 2.6.0 Moved from `WP_Scripts`.
 307       *
 308       * @param string|string[] $handles Item handle (string) or item handles (array of strings).
 309       */
 310  	public function enqueue( $handles ) {
 311          foreach ( (array) $handles as $handle ) {
 312              $handle = explode( '?', $handle );
 313  
 314              if ( ! in_array( $handle[0], $this->queue, true ) && isset( $this->registered[ $handle[0] ] ) ) {
 315                  $this->queue[] = $handle[0];
 316  
 317                  // Reset all dependencies so they must be recalculated in recurse_deps().
 318                  $this->all_queued_deps = null;
 319  
 320                  if ( isset( $handle[1] ) ) {
 321                      $this->args[ $handle[0] ] = $handle[1];
 322                  }
 323              }
 324          }
 325      }
 326  
 327      /**
 328       * Dequeue an item or items.
 329       *
 330       * Decodes handles and arguments, then dequeues handles
 331       * and removes arguments from the class property $args.
 332       *
 333       * @since 2.1.0
 334       * @since 2.6.0 Moved from `WP_Scripts`.
 335       *
 336       * @param string|string[] $handles Item handle (string) or item handles (array of strings).
 337       */
 338  	public function dequeue( $handles ) {
 339          foreach ( (array) $handles as $handle ) {
 340              $handle = explode( '?', $handle );
 341              $key    = array_search( $handle[0], $this->queue, true );
 342  
 343              if ( false !== $key ) {
 344                  // Reset all dependencies so they must be recalculated in recurse_deps().
 345                  $this->all_queued_deps = null;
 346  
 347                  unset( $this->queue[ $key ] );
 348                  unset( $this->args[ $handle[0] ] );
 349              }
 350          }
 351      }
 352  
 353      /**
 354       * Recursively search the passed dependency tree for $handle.
 355       *
 356       * @since 4.0.0
 357       *
 358       * @param string[] $queue  An array of queued _WP_Dependency handles.
 359       * @param string   $handle Name of the item. Should be unique.
 360       * @return bool Whether the handle is found after recursively searching the dependency tree.
 361       */
 362  	protected function recurse_deps( $queue, $handle ) {
 363          if ( isset( $this->all_queued_deps ) ) {
 364              return isset( $this->all_queued_deps[ $handle ] );
 365          }
 366  
 367          $all_deps = array_fill_keys( $queue, true );
 368          $queues   = array();
 369          $done     = array();
 370  
 371          while ( $queue ) {
 372              foreach ( $queue as $queued ) {
 373                  if ( ! isset( $done[ $queued ] ) && isset( $this->registered[ $queued ] ) ) {
 374                      $deps = $this->registered[ $queued ]->deps;
 375                      if ( $deps ) {
 376                          $all_deps += array_fill_keys( $deps, true );
 377                          array_push( $queues, $deps );
 378                      }
 379                      $done[ $queued ] = true;
 380                  }
 381              }
 382              $queue = array_pop( $queues );
 383          }
 384  
 385          $this->all_queued_deps = $all_deps;
 386  
 387          return isset( $this->all_queued_deps[ $handle ] );
 388      }
 389  
 390      /**
 391       * Query list for an item.
 392       *
 393       * @since 2.1.0
 394       * @since 2.6.0 Moved from `WP_Scripts`.
 395       *
 396       * @param string $handle Name of the item. Should be unique.
 397       * @param string $list   Optional. Property name of list array. Default 'registered'.
 398       * @return bool|_WP_Dependency Found, or object Item data.
 399       */
 400  	public function query( $handle, $list = 'registered' ) {
 401          switch ( $list ) {
 402              case 'registered':
 403              case 'scripts': // Back compat.
 404                  if ( isset( $this->registered[ $handle ] ) ) {
 405                      return $this->registered[ $handle ];
 406                  }
 407                  return false;
 408  
 409              case 'enqueued':
 410              case 'queue':
 411                  if ( in_array( $handle, $this->queue, true ) ) {
 412                      return true;
 413                  }
 414                  return $this->recurse_deps( $this->queue, $handle );
 415  
 416              case 'to_do':
 417              case 'to_print': // Back compat.
 418                  return in_array( $handle, $this->to_do, true );
 419  
 420              case 'done':
 421              case 'printed': // Back compat.
 422                  return in_array( $handle, $this->done, true );
 423          }
 424          return false;
 425      }
 426  
 427      /**
 428       * Set item group, unless already in a lower group.
 429       *
 430       * @since 2.8.0
 431       *
 432       * @param string    $handle    Name of the item. Should be unique.
 433       * @param bool      $recursion Internal flag that calling function was called recursively.
 434       * @param int|false $group     Group level: level (int), no groups (false).
 435       * @return bool Not already in the group or a lower group.
 436       */
 437  	public function set_group( $handle, $recursion, $group ) {
 438          $group = (int) $group;
 439  
 440          if ( isset( $this->groups[ $handle ] ) && $this->groups[ $handle ] <= $group ) {
 441              return false;
 442          }
 443  
 444          $this->groups[ $handle ] = $group;
 445  
 446          return true;
 447      }
 448  
 449  }


Generated: Tue May 19 15:51:04 2020 Cross-referenced by PHPXref 0.7.1