WordPress 4.5
[autoinstalls/wordpress.git] / wp-includes / class.wp-dependencies.php
index 158d3e03e79ff3dd1badbffba42dfc2b63d75da7..03484181cf2f44c7648cd5cdc33213773fd60635 100644 (file)
@@ -1,14 +1,19 @@
 <?php
 /**
- * BackPress Scripts enqueue
+ * Dependencies API: WP_Dependencies base class
  *
- * Classes were refactored from the WP_Scripts and WordPress script enqueue API.
+ * @since 2.6.0
  *
- * @since BackPress r74
+ * @package WordPress
+ * @subpackage Dependencies
+ */
+
+/**
+ * Core base class extended to register items.
  *
- * @package BackPress
+ * @package WordPress
+ * @since 2.6.0
  * @uses _WP_Dependency
- * @since r74
  */
 class WP_Dependencies {
        /**
@@ -18,7 +23,7 @@ class WP_Dependencies {
         * @since 2.6.8
         * @var array
         */
-       var $registered = array();
+       public $registered = array();
 
        /**
         * An array of queued _WP_Dependency handle objects.
@@ -27,7 +32,7 @@ class WP_Dependencies {
         * @since 2.6.8
         * @var array
         */
-       var $queue = array();
+       public $queue = array();
 
        /**
         * An array of _WP_Dependency handle objects to queue.
@@ -36,7 +41,7 @@ class WP_Dependencies {
         * @since 2.6.0
         * @var array
         */
-       var $to_do = array();
+       public $to_do = array();
 
        /**
         * An array of _WP_Dependency handle objects already queued.
@@ -45,7 +50,7 @@ class WP_Dependencies {
         * @since 2.6.0
         * @var array
         */
-       var $done = array();
+       public $done = array();
 
        /**
         * An array of additional arguments passed when a handle is registered.
@@ -56,7 +61,7 @@ class WP_Dependencies {
         * @since 2.6.0
         * @var array
         */
-       var $args = array();
+       public $args = array();
 
        /**
         * An array of handle groups to enqueue.
@@ -65,55 +70,42 @@ class WP_Dependencies {
         * @since 2.8.0
         * @var array
         */
-       var $groups = array();
+       public $groups = array();
 
        /**
         * A handle group to enqueue.
         *
         * @access public
         * @since 2.8.0
+        * @deprecated 4.5.0
         * @var int
         */
-       var $group = 0;
+       public $group = 0;
 
        /**
-        * Process the items and dependencies.
+        * Processes the items and dependencies.
         *
         * Processes the items passed to it or the queue, and their dependencies.
         *
         * @access public
-        * @since 2.1.0
+        * @since 2.6.0
+        * @since 2.8.0 Added the `$group` parameter.
         *
         * @param mixed $handles Optional. Items to be processed: Process queue (false), process item (string), process items (array of strings).
         * @param mixed $group   Group level: level (int), no groups (false).
         * @return array Handles of items that have been processed.
         */
        public function do_items( $handles = false, $group = false ) {
-               /**
+               /*
                 * If nothing is passed, print the queue. If a string is passed,
                 * print that item. If an array is passed, print those items.
                 */
                $handles = false === $handles ? $this->queue : (array) $handles;
                $this->all_deps( $handles );
 
-               foreach( $this->to_do as $key => $handle ) {
+               foreach ( $this->to_do as $key => $handle ) {
                        if ( !in_array($handle, $this->done, true) && isset($this->registered[$handle]) ) {
-
-                               /**
-                                * A single item may alias a set of items, by having dependencies,
-                                * but no source. Queuing the item queues the dependencies.
-                                *
-                                * Example: The extending class WP_Scripts is used to register 'scriptaculous' as a set of registered handles:
-                                *   <code>add( 'scriptaculous', false, array( 'scriptaculous-dragdrop', 'scriptaculous-slider', 'scriptaculous-controls' ) );</code>
-                                *
-                                * The src property is false.
-                               **/
-                               if ( ! $this->registered[$handle]->src ) {
-                                       $this->done[] = $handle;
-                                       continue;
-                               }
-
-                               /**
+                               /*
                                 * Attempt to process the item. If successful,
                                 * add the handle to the done array.
                                 *
@@ -130,7 +122,7 @@ class WP_Dependencies {
        }
 
        /**
-        * Process a dependency.
+        * Processes a dependency.
         *
         * @access public
         * @since 2.6.0
@@ -143,17 +135,19 @@ class WP_Dependencies {
        }
 
        /**
-        * Determine dependencies.
+        * Determines dependencies.
         *
         * Recursively builds an array of items to process taking
         * dependencies into account. Does NOT catch infinite loops.
         *
         * @access public
         * @since 2.1.0
+        * @since 2.6.0 Moved from `WP_Scripts`.
+        * @since 2.8.0 Added the `$group` parameter.
         *
-        * @param mixed $handles   Item handle and argument (string) or item handles and arguments (array of strings).
-        * @param bool  $recursion Internal flag that function is calling itself.
-        * @param mixed $group     Group level: (int) level, (false) no groups.
+        * @param mixed     $handles   Item handle and argument (string) or item handles and arguments (array of strings).
+        * @param bool      $recursion Internal flag that function is calling itself.
+        * @param int|false $group     Group level: (int) level, (false) no groups.
         * @return bool True on success, false on failure.
         */
        public function all_deps( $handles, $recursion = false, $group = false ) {
@@ -168,7 +162,8 @@ class WP_Dependencies {
                        if ( in_array($handle, $this->done, true) ) // Already done
                                continue;
 
-                       $moved = $this->set_group( $handle, $recursion, $group );
+                       $moved     = $this->set_group( $handle, $recursion, $group );
+                       $new_group = $this->groups[ $handle ];
 
                        if ( $queued && !$moved ) // already queued and in the right group
                                continue;
@@ -178,7 +173,7 @@ class WP_Dependencies {
                                $keep_going = false; // Item doesn't exist.
                        elseif ( $this->registered[$handle]->deps && array_diff($this->registered[$handle]->deps, array_keys($this->registered)) )
                                $keep_going = false; // Item requires dependencies that don't exist.
-                       elseif ( $this->registered[$handle]->deps && !$this->all_deps( $this->registered[$handle]->deps, true, $group ) )
+                       elseif ( $this->registered[$handle]->deps && !$this->all_deps( $this->registered[$handle]->deps, true, $new_group ) )
                                $keep_going = false; // Item requires dependencies that don't exist.
 
                        if ( ! $keep_going ) { // Either item or its dependencies don't exist.
@@ -207,13 +202,17 @@ class WP_Dependencies {
         *
         * @access public
         * @since 2.1.0
-        *
-        * @param string $handle Unique item name.
-        * @param string $src    The item url.
-        * @param array  $deps   Optional. An array of item handle strings on which this item depends.
-        * @param string $ver    Optional. Version (used for cache busting).
-        * @param mixed  $args   Optional. Custom property of the item. NOT the class property $args. Examples: $media, $in_footer.
-        * @return bool True on success, false on failure.
+        * @since 2.6.0 Moved from `WP_Scripts`.
+        *
+        * @param string           $handle Name of the item. Should be unique.
+        * @param string           $src    Full URL of the item, or path of the item relative to the WordPress root directory.
+        * @param array            $deps   Optional. An array of registered item handles this item depends on. Default empty array.
+        * @param string|bool|null $ver    Optional. String specifying item version number, if it has one, which is added to the URL
+        *                                 as a query string for cache busting purposes. If version is set to false, a version
+        *                                 number is automatically added equal to current installed WordPress version.
+        *                                 If set to null, no version is added.
+        * @param mixed            $args   Optional. Custom property of the item. NOT the class property $args. Examples: $media, $in_footer. 
+        * @return bool Whether the item has been registered. True on success, false on failure.
         */
        public function add( $handle, $src, $deps = array(), $ver = false, $args = null ) {
                if ( isset($this->registered[$handle]) )
@@ -269,6 +268,7 @@ class WP_Dependencies {
         *
         * @access public
         * @since 2.1.0
+        * @since 2.6.0 Moved from `WP_Scripts`.
         *
         * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings).
         * @return void
@@ -288,6 +288,7 @@ class WP_Dependencies {
         *
         * @access public
         * @since 2.1.0
+        * @since 2.6.0 Moved from `WP_Scripts`.
         *
         * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings).
         */
@@ -310,6 +311,7 @@ class WP_Dependencies {
         *
         * @access public
         * @since 2.1.0
+        * @since 2.6.0 Moved from `WP_Scripts`.
         *
         * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings).
         */
@@ -324,15 +326,41 @@ class WP_Dependencies {
                }
        }
 
+       /**
+        * Recursively search the passed dependency tree for $handle
+        *
+        * @since 4.0.0
+        *
+        * @param array  $queue  An array of queued _WP_Dependency handle objects.
+        * @param string $handle Name of the item. Should be unique.
+        * @return bool Whether the handle is found after recursively searching the dependency tree.
+        */
+       protected function recurse_deps( $queue, $handle ) {
+               foreach ( $queue as $queued ) {
+                       if ( ! isset( $this->registered[ $queued ] ) ) {
+                               continue;
+                       }
+
+                       if ( in_array( $handle, $this->registered[ $queued ]->deps ) ) {
+                               return true;
+                       } elseif ( $this->recurse_deps( $this->registered[ $queued ]->deps, $handle ) ) {
+                               return true;
+                       }
+               }
+
+               return false;
+       }
+
        /**
         * Query list for an item.
         *
         * @access public
         * @since 2.1.0
+        * @since 2.6.0 Moved from `WP_Scripts`.
         *
         * @param string $handle Name of the item. Should be unique.
         * @param string $list   Property name of list array.
-        * @return bool Found, or object Item data.
+        * @return bool|_WP_Dependency Found, or object Item data.
         */
        public function query( $handle, $list = 'registered' ) {
                switch ( $list ) {
@@ -344,7 +372,10 @@ class WP_Dependencies {
 
                        case 'enqueued' :
                        case 'queue' :
-                               return in_array( $handle, $this->queue );
+                               if ( in_array( $handle, $this->queue ) ) {
+                                       return true;
+                               }
+                               return $this->recurse_deps( $this->queue, $handle );
 
                        case 'to_do' :
                        case 'to_print': // back compat
@@ -371,15 +402,12 @@ class WP_Dependencies {
        public function set_group( $handle, $recursion, $group ) {
                $group = (int) $group;
 
-               if ( $recursion )
-                       $group = min($this->group, $group);
-               else
-                       $this->group = $group;
-
-               if ( isset($this->groups[$handle]) && $this->groups[$handle] <= $group )
+               if ( isset( $this->groups[ $handle ] ) && $this->groups[ $handle ] <= $group ) {
                        return false;
+               }
+
+               $this->groups[ $handle ] = $group;
 
-               $this->groups[$handle] = $group;
                return true;
        }
 
@@ -401,7 +429,7 @@ class _WP_Dependency {
         * @since 2.6.0
         * @var null
         */
-       var $handle;
+       public $handle;
 
        /**
         * The handle source.
@@ -410,7 +438,7 @@ class _WP_Dependency {
         * @since 2.6.0
         * @var null
         */
-       var $src;
+       public $src;
 
        /**
         * An array of handle dependencies.
@@ -419,7 +447,7 @@ class _WP_Dependency {
         * @since 2.6.0
         * @var array
         */
-       var $deps = array();
+       public $deps = array();
 
        /**
         * The handle version.
@@ -430,7 +458,7 @@ class _WP_Dependency {
         * @since 2.6.0
         * @var bool|string
         */
-       var $ver = false;
+       public $ver = false;
 
        /**
         * Additional arguments for the handle.
@@ -439,7 +467,7 @@ class _WP_Dependency {
         * @since 2.6.0
         * @var null
         */
-       var $args = null;  // Custom property, such as $in_footer or $media.
+       public $args = null;  // Custom property, such as $in_footer or $media.
 
        /**
         * Extra data to supply to the handle.
@@ -448,14 +476,14 @@ class _WP_Dependency {
         * @since 2.6.0
         * @var array
         */
-       var $extra = array();
+       public $extra = array();
 
        /**
         * Setup dependencies.
         *
         * @since 2.6.0
         */
-       function __construct() {
+       public function __construct() {
                @list( $this->handle, $this->src, $this->deps, $this->ver, $this->args ) = func_get_args();
                if ( ! is_array($this->deps) )
                        $this->deps = array();
@@ -471,7 +499,7 @@ class _WP_Dependency {
         * @param mixed  $data The data value to add.
         * @return bool False if not scalar, true otherwise.
         */
-       function add_data( $name, $data ) {
+       public function add_data( $name, $data ) {
                if ( !is_scalar($name) )
                        return false;
                $this->extra[$name] = $data;