[Summary view] [Print] [Text view]

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