WordPress.org

Make WordPress Core

Ticket #23914: class.wp-dependencies.php.patch

File class.wp-dependencies.php.patch, 8.7 KB (added by kitchin, 11 months ago)

Some improvements, tell me if want an interdiff.

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

     
    2121        var $queue = array(); 
    2222        var $to_do = array(); 
    2323        var $done = array(); 
    24         var $args = array(); 
    25         var $groups = array(); 
    26         var $group = 0; 
     24        var $args = array();  // In extending classes, strings appended to item urls. 
     25        var $groups = array();  // In extending class WP_Scripts, header and footer groups. 
     26        var $group = 0;  // Internal group state. 
    2727 
    2828        /** 
    2929         * Do the dependencies 
    3030         * 
    31          * Process the items passed to it or the queue. Processes all dependencies. 
     31         * Processes the items passed to it or the queue. Processes all dependencies. 
    3232         * 
    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 
     33         * @param mixed $handles (optional) Items to be processed: (false) Process queue, (string) process item, (array of strings) process items 
     34         * @param mixed $group Group level: (int) level, (false) no groups 
     35         * @return array Handles of items that have been processed 
    3536         */ 
    3637        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. 
     38                // Print the queue if nothing is passed. If a string is passed, print that item. If an array is passed, print those items. 
    3839                $handles = false === $handles ? $this->queue : (array) $handles; 
    3940                $this->all_deps( $handles ); 
    4041 
    4142                foreach( $this->to_do as $key => $handle ) { 
    4243                        if ( !in_array($handle, $this->done, true) && isset($this->registered[$handle]) ) { 
    4344 
    44                                 if ( ! $this->registered[$handle]->src ) { // Defines a group. 
     45                                /** 
     46                                 * A single item may alias a set of items, by having dependencies but no src. 
     47                                 * Queuing the item queues the dependencies. 
     48                                 * Example: the extending class WP_Scripts is used to register 'scriptaculous' as a set of registered handles: 
     49                                 *   add( 'scriptaculous', false, array('scriptaculous-dragdrop', 'scriptaculous-slider', 'scriptaculous-controls') ); 
     50                                 * The src property is false. 
     51                                **/ 
     52                                if ( ! $this->registered[$handle]->src ) { 
    4553                                        $this->done[] = $handle; 
    4654                                        continue; 
    4755                                } 
    … …  
    5664                return $this->done; 
    5765        } 
    5866 
     67        /** 
     68         * Do dependency 
     69         * 
     70         * Processes one item for dependencies. 
     71         * 
     72         * @param string $handle Unique item name 
     73         * @return bool Success 
     74         */ 
    5975        function do_item( $handle ) { 
    6076                return isset($this->registered[$handle]); 
    6177        } 
    6278 
    6379        /** 
    64          * Determines dependencies 
     80         * Determine dependencies 
    6581         * 
    66          * Recursively builds array of items to process taking dependencies into account. Does NOT catch infinite loops. 
     82         * Recursively builds array of items to process taking dependencies into account. 
     83         * Does NOT catch infinite loops. 
    6784         * 
    68          * 
    69          * @param mixed $handles Accepts (string) dep name or (array of strings) dep names 
    70          * @param bool $recursion Used internally when function calls itself 
     85         * @param mixed $handles (string) Dependency handle and argument or (array of strings) Dependency handles and arguments 
     86         * @param bool $recursion Internal flag that function is calling itself 
     87         * @param mixed $group Group level: (int) level, (false) no groups 
     88         * @return bool Success 
    7189         */ 
    7290        function all_deps( $handles, $recursion = false, $group = false ) { 
    7391                if ( !$handles = (array) $handles ) 
    … …  
    88106 
    89107                        $keep_going = true; 
    90108                        if ( !isset($this->registered[$handle]) ) 
    91                                 $keep_going = false; // Script doesn't exist 
     109                                $keep_going = false; // Item doesn't exist 
    92110                        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?) 
     111                                $keep_going = false; // Item requires deps which don't exist (not a necessary check. efficiency?) 
    94112                        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 
     113                                $keep_going = false; // Item requires deps which don't exist 
    96114 
    97                         if ( !$keep_going ) { // Either script or its deps don't exist. 
     115                        if ( !$keep_going ) { // Either item or its deps don't exist. 
    98116                                if ( $recursion ) 
    99117                                        return false; // Abort this branch. 
    100118                                else 
    … …  
    114132        } 
    115133 
    116134        /** 
    117          * Adds item 
     135         * Register item 
    118136         * 
    119          * Adds the item only if no item of that name already exists 
     137         * Registers the item if no item of that name already exists. 
    120138         * 
    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 
     139         * @param string $handle Unique item name 
     140         * @param string $src Item url 
     141         * @param array of strings $deps (optional) Item handles on which this item depends 
     142         * @param string $ver (optional) Version (used for cache busting) 
     143         * @param mixed $args (optional) Custom property of the item. NOT the class property $args. Examples: $media, $in_footer. 
     144         * @return bool Success 
    126145         */ 
    127146        function add( $handle, $src, $deps = array(), $ver = false, $args = null ) { 
    128147                if ( isset($this->registered[$handle]) ) 
    … …  
    132151        } 
    133152 
    134153        /** 
    135          * Adds extra data 
     154         * Add extra data 
    136155         * 
    137          * Adds data only if script has already been added. 
     156         * Adds data if item has been registered. 
    138157         * 
    139          * @param string $handle Script name 
    140          * @param string $key 
    141          * @param mixed $value 
    142          * @return bool success 
     158         * @param string $handle Unique item name 
     159         * @param string $key Data key 
     160         * @param mixed $value Data value 
     161         * @return bool Success 
    143162         */ 
    144163        function add_data( $handle, $key, $value ) { 
    145164                if ( !isset( $this->registered[$handle] ) ) 
    … …  
    151170        /** 
    152171         * Get extra data 
    153172         * 
    154          * Gets data associated with a certain handle. 
     173         * Gets data associated with a registered item. 
    155174         * 
    156175         * @since WP 3.3 
    157176         * 
    158          * @param string $handle Script name 
    159          * @param string $key 
    160          * @return mixed 
     177         * @param string $handle Unique item name 
     178         * @param string $key Data key 
     179         * @return mixed Data value 
    161180         */ 
    162181        function get_data( $handle, $key ) { 
    163182                if ( !isset( $this->registered[$handle] ) ) 
    … …  
    169188                return $this->registered[$handle]->extra[$key]; 
    170189        } 
    171190 
     191        /** 
     192         * Unregister items 
     193         * 
     194         * @param mixed $handles (string) Item handle or (array of strings) Item handles 
     195         * @return void 
     196         */ 
    172197        function remove( $handles ) { 
    173198                foreach ( (array) $handles as $handle ) 
    174199                        unset($this->registered[$handle]); 
    175200        } 
    176201 
     202        /** 
     203         * Queue items 
     204         * 
     205         * Decodes handles and arguments, then queues handles and stores arguments in the class property $args. 
     206         * For example in extending classes, $args is appended to the item url as a query string. 
     207         * Note $args is NOT the $args property of items in the $registered array. 
     208         * 
     209         * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments 
     210         * @return void 
     211         */ 
    177212        function enqueue( $handles ) { 
    178213                foreach ( (array) $handles as $handle ) { 
    179214                        $handle = explode('?', $handle); 
    … …  
    185220                } 
    186221        } 
    187222 
     223        /** 
     224         * Dequeue items 
     225         * 
     226         * Decodes handles and arguments, then dequeues handles and removes arguments from the class property $args. 
     227         * 
     228         * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments 
     229         * @return void 
     230         */ 
    188231        function dequeue( $handles ) { 
    189232                foreach ( (array) $handles as $handle ) { 
    190233                        $handle = explode('?', $handle); 
    … …  
    196239                } 
    197240        } 
    198241 
    199  
     242        /** 
     243         * Query list for item 
     244         * 
     245         * @param $handle (string) Item handle 
     246         * @param $list (string) Property name of list array 
     247         * @return bool Found, or object Item data 
     248         */ 
    200249        function query( $handle, $list = 'registered' ) { 
    201250                switch ( $list ) { 
    202251                        case 'registered' : 
    … …  
    220269                return false; 
    221270        } 
    222271 
     272        /** 
     273         * Set item group, unless already in a lower group 
     274         * 
     275         * @param $handle (string) Item handle 
     276         * @param bool $recursion Internal flag that calling function was called recusively 
     277         * @param mixed $group Group level 
     278         * @return bool Not already in the group or a lower group 
     279         */ 
    223280        function set_group( $handle, $recursion, $group ) { 
    224281                $group = (int) $group; 
    225282 
    … …  
    242299        var $src; 
    243300        var $deps = array(); 
    244301        var $ver = false; 
    245         var $args = null; 
    246  
     302        var $args = null;  // Custom property, such as $in_footer or $media. 
    247303        var $extra = array(); 
    248304 
    249305        function __construct() {