WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
09/20/2013 07:53:53 PM (13 years ago)
Author:
DrewAPicture
Message:

Inline documentation for WP_Dependencies and _WP_Dependency classes.

Props kitchin for the initial patch.
Fixes #23914.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r25518 r25524  
    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 *
    159 * @package BackPress
    … …  
    8478
    8579        /**
    86          * Do the dependencies
    87          *
    88          * Process the items passed to it or the queue. Processes all dependencies.
    89          *
    90          * @param mixed $handles (optional) items to be processed. (void) processes queue, (string) process that item, (array of strings) process those items
    91          * @return array Items that have been processed
    92          */
    93         function do_items( $handles = false, $group = false ) {
    94                 // Print the queue if nothing is passed. If a string is passed, print that script. If an array is passed, print those scripts.
     80         * Process the items and dependencies.
     81         *
     82         * Processes the items passed to it or the queue, and their dependencies.
     83         *
     84         * @access public
     85         * @since 2.1.0
     86         *
     87         * @param mixed $handles Optional. Items to be processed: Process queue (false), process item (string), process items (array of strings).
     88         * @param mixed $group   Group level: level (int), no groups (false).
     89         * @return array Handles of items that have been processed.
     90         */
     91        public function do_items( $handles = false, $group = false ) {
     92                /**
     93                 * If nothing is passed, print the queue. If a string is passed,
     94                 * print that item. If an array is passed, print those items.
     95                 */
    9596                $handles = false === $handles ? $this->queue : (array) $handles;
    9697                $this->all_deps( $handles );
    … …  
    99100                        if ( !in_array($handle, $this->done, true) && isset($this->registered[$handle]) ) {
    100101
    101                                 if ( ! $this->registered[$handle]->src ) { // Defines a group.
     102                                /**
     103                                 * A single item may alias a set of items, by having dependencies,
     104                                 * but no source. Queuing the item queues the dependencies.
     105                                 *
     106                                 * Example: The extending class WP_Scripts is used to register 'scriptaculous' as a set of registered handles:
     107                                 *   <code>add( 'scriptaculous', false, array( 'scriptaculous-dragdrop', 'scriptaculous-slider', 'scriptaculous-controls' ) );</code>
     108                                 *
     109                                 * The src property is false.
     110                                **/
     111                                if ( ! $this->registered[$handle]->src ) {
    102112                                        $this->done[] = $handle;
    103113                                        continue;
    104114                                }
    105115
     116                                /**
     117                                 * Attempt to process the item. If successful,
     118                                 * add the handle to the done array.
     119                                 *
     120                                 * Unset the item from the to_do array.
     121                                 */
    106122                                if ( $this->do_item( $handle, $group ) )
    107123                                        $this->done[] = $handle;
    … …  
    114130        }
    115131
    116         function do_item( $handle ) {
     132        /**
     133         * Process a dependency.
     134         *
     135         * @access public
     136         * @since 2.6.0
     137         *
     138         * @param string $handle Name of the item. Should be unique.
     139         * @return bool True on success, false if not set.
     140         */
     141        public function do_item( $handle ) {
    117142                return isset($this->registered[$handle]);
    118143        }
    119144
    120145        /**
    121          * Determines dependencies
    122          *
    123          * Recursively builds array of items to process taking dependencies into account. Does NOT catch infinite loops.
    124          *
    125          *
    126          * @param mixed $handles Accepts (string) dep name or (array of strings) dep names
    127          * @param bool $recursion Used internally when function calls itself
    128          */
    129         function all_deps( $handles, $recursion = false, $group = false ) {
     146         * Determine dependencies.
     147         *
     148         * Recursively builds an array of items to process taking
     149         * dependencies into account. Does NOT catch infinite loops.
     150         *
     151         * @access public
     152         * @since 2.1.0
     153         *
     154         * @param mixed $handles   Item handle and argument (string) or item handles and arguments (array of strings).
     155         * @param bool  $recursion Internal flag that function is calling itself.
     156         * @param mixed $group     Group level: (int) level, (false) no groups.
     157         * @return bool True on success, false on failure.
     158         */
     159        public function all_deps( $handles, $recursion = false, $group = false ) {
    130160                if ( !$handles = (array) $handles )
    131161                        return false;
    … …  
    146176                        $keep_going = true;
    147177                        if ( !isset($this->registered[$handle]) )
    148                                 $keep_going = false; // Script doesn't exist
     178                                $keep_going = false; // Item doesn't exist.
    149179                        elseif ( $this->registered[$handle]->deps && array_diff($this->registered[$handle]->deps, array_keys($this->registered)) )
    150                                 $keep_going = false; // Script requires deps which don't exist (not a necessary check. efficiency?)
     180                                $keep_going = false; // Item requires dependencies that don't exist.
    151181                        elseif ( $this->registered[$handle]->deps && !$this->all_deps( $this->registered[$handle]->deps, true, $group ) )
    152                                 $keep_going = false; // Script requires deps which don't exist
    153 
    154                         if ( !$keep_going ) { // Either script or its deps don't exist.
     182                                $keep_going = false; // Item requires dependencies that don't exist.
     183
     184                        if ( ! $keep_going ) { // Either item or its dependencies don't exist.
    155185                                if ( $recursion )
    156186                                        return false; // Abort this branch.
    … …  
    159189                        }
    160190
    161                         if ( $queued ) // Already grobbed it and its deps
     191                        if ( $queued ) // Already grabbed it and its dependencies.
    162192                                continue;
    163193
    … …  
    172202
    173203        /**
    174          * Adds item
    175          *
    176          * Adds the item only if no item of that name already exists
    177          *
    178          * @param string $handle Script name
    179          * @param string $src Script url
    180          * @param array $deps (optional) Array of script names on which this script depends
    181          * @param string $ver (optional) Script version (used for cache busting)
    182          * @return array Hierarchical array of dependencies
    183          */
    184         function add( $handle, $src, $deps = array(), $ver = false, $args = null ) {
     204         * Register an item.
     205         *
     206         * Registers the item if no item of that name already exists.
     207         *
     208         * @access public
     209         * @since 2.1.0
     210         *
     211         * @param string $handle Unique item name.
     212         * @param string $src    The item url.
     213         * @param array  $deps   Optional. An array of item handle strings on which this item depends.
     214         * @param string $ver    Optional. Version (used for cache busting).
     215         * @param mixed  $args   Optional. Custom property of the item. NOT the class property $args. Examples: $media, $in_footer.
     216         * @return bool True on success, false on failure.
     217         */
     218        public function add( $handle, $src, $deps = array(), $ver = false, $args = null ) {
    185219                if ( isset($this->registered[$handle]) )
    186220                        return false;
    … …  
    190224
    191225        /**
    192          * Adds extra data
    193          *
    194          * Adds data only if script has already been added.
    195          *
    196          * @param string $handle Script name
    197          * @param string $key
    198          * @param mixed $value
    199          * @return bool success
    200          */
    201         function add_data( $handle, $key, $value ) {
     226         * Add extra item data.
     227         *
     228         * Adds data to a registered item.
     229         *
     230         * @access public
     231         * @since 2.6.0
     232         *
     233         * @param string $handle Name of the item. Should be unique.
     234         * @param string $key    The data key.
     235         * @param mixed  $value  The data value.
     236         * @return bool True on success, false on failure.
     237         */
     238        public function add_data( $handle, $key, $value ) {
    202239                if ( !isset( $this->registered[$handle] ) )
    203240                        return false;
    … …  
    207244
    208245        /**
    209          * Get extra data
    210          *
    211          * Gets data associated with a certain handle.
    212          *
    213          * @since WP 3.3
    214          *
    215          * @param string $handle Script name
    216          * @param string $key
    217          * @return mixed
    218          */
    219         function get_data( $handle, $key ) {
     246         * Get extra item data.
     247         *
     248         * Gets data associated with a registered item.
     249         *
     250         * @access public
     251         * @since 3.3.0
     252         *
     253         * @param string $handle Name of the item. Should be unique.
     254         * @param string $key    The data key.
     255         * @return mixed Extra item data (string), false otherwise.
     256         */
     257        public function get_data( $handle, $key ) {
    220258                if ( !isset( $this->registered[$handle] ) )
    221259                        return false;
    … …  
    227265        }
    228266
    229         function remove( $handles ) {
     267        /**
     268         * Un-register an item or items.
     269         *
     270         * @access public
     271         * @since 2.1.0
     272         *
     273         * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings).
     274         * @return void
     275         */
     276        public function remove( $handles ) {
    230277                foreach ( (array) $handles as $handle )
    231278                        unset($this->registered[$handle]);
    232279        }
    233280
    234         function enqueue( $handles ) {
     281        /**
     282         * Queue an item or items.
     283         *
     284         * Decodes handles and arguments, then queues handles and stores
     285         * arguments in the class property $args. For example in extending
     286         * classes, $args is appended to the item url as a query string.
     287         * Note $args is NOT the $args property of items in the $registered array.
     288         *
     289         * @access public
     290         * @since 2.1.0
     291         *
     292         * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings).
     293         */
     294        public function enqueue( $handles ) {
    235295                foreach ( (array) $handles as $handle ) {
    236296                        $handle = explode('?', $handle);
    … …  
    243303        }
    244304
    245         function dequeue( $handles ) {
     305        /**
     306         * Dequeue an item or items.
     307         *
     308         * Decodes handles and arguments, then dequeues handles
     309         * and removes arguments from the class property $args.
     310         *
     311         * @access public
     312         * @since 2.1.0
     313         *
     314         * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings).
     315         */
     316        public function dequeue( $handles ) {
    246317                foreach ( (array) $handles as $handle ) {
    247318                        $handle = explode('?', $handle);
    … …  
    254325        }
    255326
    256 
    257         function query( $handle, $list = 'registered' ) {
     327        /**
     328         * Query list for an item.
     329         *
     330         * @access public
     331         * @since 2.1.0
     332         *
     333         * @param string $handle Name of the item. Should be unique.
     334         * @param string $list   Property name of list array.
     335         * @return bool Found, or object Item data.
     336         */
     337        public function query( $handle, $list = 'registered' ) {
    258338                switch ( $list ) {
    259339                        case 'registered' :
    … …  
    278358        }
    279359
    280         function set_group( $handle, $recursion, $group ) {
     360        /**
     361         * Set item group, unless already in a lower group.
     362         *
     363         * @access public
     364         * @since 2.8.0
     365         *
     366         * @param string $handle    Name of the item. Should be unique.
     367         * @param bool   $recursion Internal flag that calling function was called recursively.
     368         * @param mixed  $group     Group level.
     369         * @return bool Not already in the group or a lower group
     370         */
     371        public function set_group( $handle, $recursion, $group ) {
    281372                $group = (int) $group;
    282373
    … …  
    293384        }
    294385
    295 }
    296 
     386} // WP_Dependencies
     387
     388/**
     389 * Class _WP_Dependency
     390 *
     391 * Helper class to register a handle and associated data.
     392 *
     393 * @access private
     394 * @since 2.6.0
     395 */
    297396class _WP_Dependency {
    298397        /**
    … …  
    352451        var $extra = array();
    353452
     453        /**
     454         * Setup dependencies.
     455         *
     456         * @since 2.6.0
     457         */
    354458        function __construct() {
    355459                @list( $this->handle, $this->src, $this->deps, $this->ver, $this->args ) = func_get_args();
    … …  
    358462        }
    359463
     464        /**
     465         * Add handle data.
     466         *
     467         * @access public
     468         * @since 2.6.0
     469         *
     470         * @param string $name The data key to add.
     471         * @param mixed  $data The data value to add.
     472         * @return bool False if not scalar, true otherwise.
     473         */
    360474        function add_data( $name, $data ) {
    361475                if ( !is_scalar($name) )
    … …  
    364478                return true;
    365479        }
    366 }
     480
     481} // _WP_Dependencies
Note: See TracChangeset for help on using the changeset viewer.