WordPress.org
Get WordPress

Make WordPress Core

Ticket #23914: 23914.2.diff

File 23914.2.diff, 11.8 KB (added by DrewAPicture, 12 years ago)

Separated out properties to separate patches

  • src/wp-includes/class.wp-dependencies.php

     
    11<?php
    22/**
    3  * BackPress Scripts enqueue.
     3 * BackPress Scripts enqueue
    44 *
    5  * These classes were refactored from the WordPress WP_Scripts and WordPress
    6  * script enqueue API.
     5 * Classes were refactored from the WP_Scripts and WordPress script enqueue API.
    76 *
    8  * @package BackPress
    9  * @since r74
    10  */
    11 
    12 /**
    13  * BackPress enqueued dependiences class.
     7 * @since BackPress r74
    148 *
    15  * @package BackPress
    16  * @uses _WP_Dependency
    17  * @since r74
     9 * @package WordPress
     10 * @subpackage BackPress
    1811 */
    1912class WP_Dependencies {
    2013        var $registered = array();
    … …  
    2619        var $group = 0;
    2720
    2821        /**
    29          * Do the dependencies
     22         * Process the dependencies.
    3023         *
    31          * Process the items passed to it or the queue. Processes all dependencies.
     24         * Processes the items passed to it or the queue. Processes all dependencies.
    3225         *
    33          * @param mixed $handles (optional) items to be processed. (void) processes queue, (string) process that item, (array of strings) process those items
    34          * @return array Items that have been processed
     26         * @access public
     27         * @since Unknown
     28         *
     29         * @param mixed $handles Optional. Items to be processed: (false) Process queue, (string) process item, (array of strings) process items.
     30         * @param mixed $group   Group level: (int) level, (false) no groups.
     31         * @return array Handles of items that have been processed.
    3532         */
    36         function do_items( $handles = false, $group = false ) {
    37                 // Print the queue if nothing is passed. If a string is passed, print that script. If an array is passed, print those scripts.
     33        public function do_items( $handles = false, $group = false ) {
     34                /**
     35                 * Print the queue if nothing is passed. If a string is passed,
     36                 * print that item. If an array is passed, print those items.
     37                 */
    3838                $handles = false === $handles ? $this->queue : (array) $handles;
    3939                $this->all_deps( $handles );
    4040
    4141                foreach( $this->to_do as $key => $handle ) {
    4242                        if ( !in_array($handle, $this->done, true) && isset($this->registered[$handle]) ) {
    4343
    44                                 if ( ! $this->registered[$handle]->src ) { // Defines a group.
     44                                /**
     45                                 * A single item may alias a set of items, by having dependencies,
     46                                 * but no source. Queuing the item queues the dependencies.
     47                                 *
     48                                 * Example: The extending class WP_Scripts is used to register 'scriptaculous' as a set of registered handles:
     49                                 *   <code>add( 'scriptaculous', false, array( 'scriptaculous-dragdrop', 'scriptaculous-slider', 'scriptaculous-controls' ) );</code>
     50                                 *
     51                                 * The src property is false.
     52                                **/
     53                                if ( ! $this->registered[$handle]->src ) {
    4554                                        $this->done[] = $handle;
    4655                                        continue;
    4756                                }
    4857
     58                                /**
     59                                 * Attempt to process the item. If successful,
     60                                 * add the handle to the 'done' array.
     61                                 */
    4962                                if ( $this->do_item( $handle, $group ) )
    5063                                        $this->done[] = $handle;
    5164
    … …  
    5669                return $this->done;
    5770        }
    5871
    59         function do_item( $handle ) {
     72        /**
     73         * Process a dependency.
     74         *
     75         * @access public
     76         * @since Unknown
     77         *
     78         * @param string $handle Unique item name.
     79         * @return bool True on success, false on failure.
     80         */
     81        public function do_item( $handle ) {
    6082                return isset($this->registered[$handle]);
    6183        }
    6284
    6385        /**
    64          * Determines dependencies
     86         * Determine dependencies.
    6587         *
    66          * Recursively builds array of items to process taking dependencies into account. Does NOT catch infinite loops.
     88         * Recursively builds an array of items to process taking
     89         * dependencies into account. Does NOT catch infinite loops.
    6790         *
     91         * @access public
     92         * @since Unknown
    6893         *
    69          * @param mixed $handles Accepts (string) dep name or (array of strings) dep names
    70          * @param bool $recursion Used internally when function calls itself
     94         * @param mixed $handles   (string) Dependency handle and argument or (array of strings) Dependency handles and arguments.
     95         * @param bool  $recursion Internal flag that function is calling itself.
     96         * @param mixed $group     Group level: (int) level, (false) no groups.
     97         * @return bool Success
    7198         */
    72         function all_deps( $handles, $recursion = false, $group = false ) {
     99        public function all_deps( $handles, $recursion = false, $group = false ) {
    73100                if ( !$handles = (array) $handles )
    74101                        return false;
    75102
    … …  
    88115
    89116                        $keep_going = true;
    90117                        if ( !isset($this->registered[$handle]) )
    91                                 $keep_going = false; // Script doesn't exist
     118                                $keep_going = false; // Item doesn't exist.
    92119                        elseif ( $this->registered[$handle]->deps && array_diff($this->registered[$handle]->deps, array_keys($this->registered)) )
    93                                 $keep_going = false; // Script requires deps which don't exist (not a necessary check. efficiency?)
     120                                $keep_going = false; // Item requires dependencies that don't exist.
    94121                        elseif ( $this->registered[$handle]->deps && !$this->all_deps( $this->registered[$handle]->deps, true, $group ) )
    95                                 $keep_going = false; // Script requires deps which don't exist
     122                                $keep_going = false; // Item requires dependencies that don't exist.
    96123
    97                         if ( !$keep_going ) { // Either script or its deps don't exist.
     124                        if ( ! $keep_going ) { // Either item or its dependencies don't exist.
    98125                                if ( $recursion )
    99126                                        return false; // Abort this branch.
    100127                                else
    101128                                        continue; // We're at the top level. Move on to the next one.
    102129                        }
    103130
    104                         if ( $queued ) // Already grobbed it and its deps
     131                        if ( $queued ) // Already grabbed it and its dependencies.
    105132                                continue;
    106133
    107134                        if ( isset($handle_parts[1]) )
    … …  
    114141        }
    115142
    116143        /**
    117          * Adds item
     144         * Register an item.
    118145         *
    119          * Adds the item only if no item of that name already exists
     146         * Registers the item if no item of that name already exists.
    120147         *
    121          * @param string $handle Script name
    122          * @param string $src Script url
    123          * @param array $deps (optional) Array of script names on which this script depends
    124          * @param string $ver (optional) Script version (used for cache busting)
    125          * @return array Hierarchical array of dependencies
     148         * @access public
     149         * @since Unknown
     150         *
     151         * @param string $handle Unique item name.
     152         * @param string $src    The item url.
     153         * @param array  $deps   Optional. An array of item handle strings on which this item depends.
     154         * @param string $ver    Optional. Version (used for cache busting).
     155         * @param mixed  $args   Optional. Custom property of the item. NOT the class property $args. Examples: $media, $in_footer.
     156         * @return bool True on success, false on failure.
    126157         */
    127         function add( $handle, $src, $deps = array(), $ver = false, $args = null ) {
     158        public function add( $handle, $src, $deps = array(), $ver = false, $args = null ) {
    128159                if ( isset($this->registered[$handle]) )
    129160                        return false;
    130161                $this->registered[$handle] = new _WP_Dependency( $handle, $src, $deps, $ver, $args );
    … …  
    132163        }
    133164
    134165        /**
    135          * Adds extra data
     166         * Add extra item data.
    136167         *
    137          * Adds data only if script has already been added.
     168         * Adds data to a registered item.
    138169         *
    139          * @param string $handle Script name
    140          * @param string $key
    141          * @param mixed $value
    142          * @return bool success
     170         * @access public
     171         * @since Unknown
     172         *
     173         * @param string $handle Unique item name.
     174         * @param string $key    Data key.
     175         * @param mixed  $value  Data value.
     176         * @return bool True on success, false on failure.
    143177         */
    144         function add_data( $handle, $key, $value ) {
     178        public function add_data( $handle, $key, $value ) {
    145179                if ( !isset( $this->registered[$handle] ) )
    146180                        return false;
    147181
    … …  
    149183        }
    150184
    151185        /**
    152          * Get extra data
     186         * Get extra item data.
    153187         *
    154          * Gets data associated with a certain handle.
     188         * Gets data associated with a registered item.
    155189         *
    156          * @since WP 3.3
     190         * @access public
     191         * @since 3.3.0
    157192         *
    158          * @param string $handle Script name
    159          * @param string $key
    160          * @return mixed
     193         * @param string $handle Unique item name.
     194         * @param string $key    Data key.
     195         * @return mixed (string) Extra item data, false otherwise.
    161196         */
    162         function get_data( $handle, $key ) {
     197        public function get_data( $handle, $key ) {
    163198                if ( !isset( $this->registered[$handle] ) )
    164199                        return false;
    165200
    … …  
    169204                return $this->registered[$handle]->extra[$key];
    170205        }
    171206
    172         function remove( $handles ) {
     207        /**
     208         * Unregister and item or items.
     209         *
     210         * @access public
     211         * @since Unknown
     212         *
     213         * @param mixed $handles (string) Item handle or (array of strings) Item handles.
     214         * @return void
     215         */
     216        public function remove( $handles ) {
    173217                foreach ( (array) $handles as $handle )
    174218                        unset($this->registered[$handle]);
    175219        }
    176220
    177         function enqueue( $handles ) {
     221        /**
     222         * Queue an item or items.
     223         *
     224         * Decodes handles and arguments, then queues handles and stores
     225         * arguments in the class property $args. For example in extending
     226         * classes, $args is appended to the item url as a query string.
     227         * Note $args is NOT the $args property of items in the $registered array.
     228         *
     229         * @access public
     230         * @since Unknown
     231         *
     232         * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments
     233         * @return void
     234         */
     235        public function enqueue( $handles ) {
    178236                foreach ( (array) $handles as $handle ) {
    179237                        $handle = explode('?', $handle);
    180238                        if ( !in_array($handle[0], $this->queue) && isset($this->registered[$handle[0]]) ) {
    … …  
    185243                }
    186244        }
    187245
    188         function dequeue( $handles ) {
     246        /**
     247         * Dequeue an item or items.
     248         *
     249         * Decodes handles and arguments, then dequeues handles
     250         * and removes arguments from the class property $args.
     251         *
     252         * @access public
     253         * @since Unknown
     254         *
     255         * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments
     256         * @return void
     257         */
     258        public function dequeue( $handles ) {
    189259                foreach ( (array) $handles as $handle ) {
    190260                        $handle = explode('?', $handle);
    191261                        $key = array_search($handle[0], $this->queue);
    … …  
    196266                }
    197267        }
    198268
    199 
    200         function query( $handle, $list = 'registered' ) {
     269        /**
     270         * Query list for an item.
     271         *
     272         * @access public
     273         * @since Unknown
     274         *
     275         * @param string $handle The item handle.
     276         * @param string $list   Property name of list array.
     277         * @return bool Found, or object Item data.
     278         */
     279        public function query( $handle, $list = 'registered' ) {
    201280                switch ( $list ) {
    202281                        case 'registered' :
    203282                        case 'scripts': // back compat
    … …  
    220299                return false;
    221300        }
    222301
    223         function set_group( $handle, $recursion, $group ) {
     302        /**
     303         * Set item group, unless already in a lower group.
     304         *
     305         * @access public
     306         * @since Unknown
     307         *
     308         * @param string $handle    The item handle.
     309         * @param bool   $recursion Internal flag that calling function was called recursively.
     310         * @param mixed  $group     Group level.
     311         * @return bool Not already in the group or a lower group
     312         */
     313        public function set_group( $handle, $recursion, $group ) {
    224314                $group = (int) $group;
    225315
    226316                if ( $recursion )
    … …  
    235325                return true;
    236326        }
    237327
    238 }
     328} // WP_Dependencies
    239329
     330/**
     331 * Class _WP_Dependency
     332 *
     333 * Helper class to register a handle and associated data.
     334 *
     335 * @access private
     336 * @since 2.6.0
     337 */
    240338class _WP_Dependency {
    241339        var $handle;
    242340        var $src;
    … …  
    246344
    247345        var $extra = array();
    248346
     347        /**
     348         * Setup dependencies.
     349         *
     350         * @since 2.6.0
     351         */
    249352        function __construct() {
    250353                @list( $this->handle, $this->src, $this->deps, $this->ver, $this->args ) = func_get_args();
    251354                if ( ! is_array($this->deps) )
    252355                        $this->deps = array();
    253356        }
    254357
     358        /**
     359         * Add handle data.
     360         *
     361         * @access public
     362         * @since 2.6.0
     363         *
     364         * @param string $name The data key to add.
     365         * @param mixed  $data The data value to add.
     366         * @return bool False if not scalar, true otherwise.
     367         */
    255368        function add_data( $name, $data ) {
    256369                if ( !is_scalar($name) )
    257370                        return false;
    258371                $this->extra[$name] = $data;
    259372                return true;
    260373        }
    261 }
     374
     375} // _WP_Dependencies