WordPress.org

Make WordPress Core

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

File class.wp-dependencies.php.patch, 8.7 KB (added by kitchin, 5 years 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() {