WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
09/20/2013 07:53:53 PM (12 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.