WordPress 4.5
[autoinstalls/wordpress.git] / wp-includes / class.wp-dependencies.php
index 918c53156f9214ffb12c052db981b10cc79d9942..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 {
        /**
@@ -72,17 +77,19 @@ class WP_Dependencies {
         *
         * @access public
         * @since 2.8.0
+        * @deprecated 4.5.0
         * @var int
         */
        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).
@@ -96,23 +103,8 @@ class WP_Dependencies {
                $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,12 +202,16 @@ 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.
+        * @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 ) {
@@ -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).
         */
@@ -354,10 +356,11 @@ class WP_Dependencies {
         *
         * @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 ) {
@@ -399,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;
        }