WordPress.org

Make WordPress Core

Ticket #5338: plugin.r6334.patch

File plugin.r6334.patch, 14.5 KB (added by darkdragon, 11 years ago)

Optimizations with PHPDoc updates

  • plugin.php

     
    77 * The API callback examples reference functions, but can be methods of classes.
    88 * To hook methods, you'll need to pass an array one of two ways.
    99 *
    10  * For static methods (you won't have access to the <tt>$this</tt> variable in the
    11  * method):
    12  * <code>array('class_name', 'method_name');</code>
    13  *
    14  * The second method will need the reference to the object to have access to the
    15  * method.
    16  * <code>array(&$this, 'method_name');</code>
    17  * <code>
    18  * $obj = new myObject();
    19  * array(&$obj, 'method_name');
    20  * </code>
    2110 * Any of the syntaxes explained in the PHP documentation for the
    22  * {@link http://us2.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback' type} are valid.
     11 * {@link http://us2.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback'}
     12 * type are valid.
    2313 *
    2414 * Also see the {@link http://codex.wordpress.org/Plugin_API Plugin API} for more information
    2515 * and examples on how to use a lot of these functions.
     
    3020 */
    3121
    3222/**
    33  * Hooks a function or method to a specific filter action.
     23 * add_filter() - Hooks a function or method to a specific filter action.
    3424 *
    3525 * Filters are the hooks that WordPress launches to modify text of various types
    3626 * before adding it to the database or sending it to the browser screen. Plugins
     
    5848 *
    5949 * @package WordPress
    6050 * @subpackage Plugin
    61  * @since 1.5
     51 * @since 0.71
    6252 * @global array $wp_filter Stores all of the filters added in the form of
    6353 *      wp_filter['tag']['array of priorities']['array of functions serialized']['array of ['array (functions, accepted_args)]']
    6454 * @global array $merged_filters Tracks the tags that need to be merged for later. If the hook is added, it doesn't need to run through that process.
     
    7969}
    8070
    8171/**
    82  * Check if any filter has been registered for a hook.  Optionally returns the priority on that hook for the specified function.
     72 * has_filter() - Check if any filter has been registered for a hook.
     73 *
    8374 * @package WordPress
    8475 * @subpackage Plugin
    8576 * @since 2.4
     
    8778 *
    8879 * @param string $tag The name of the filter hook.
    8980 * @param callback $function_to_check optional.  If specified, return the priority of that function on this hook or false if not attached.
    90  * @return int|boolean
     81 * @return int|boolean Optionally returns the priority on that hook for the specified function.
    9182 */
    9283function has_filter($tag, $function_to_check = false) {
    9384        global $wp_filter;
     
    10899}
    109100
    110101/**
    111  * Call the functions added to a filter hook.
     102 * apply_filters() - Call the functions added to a filter hook.
    112103 *
    113104 * The callback functions attached to filter hook <tt>$tag</tt> are invoked by
    114105 * calling this function. This function can be used to create a new filter hook
     
    120111 * function example_hook($string, $arg1, $arg2)
    121112 * {
    122113 *              //Do stuff
     114 *              return $string;
    123115 * }
    124116 * $value = apply_filters('example_filter', 'filter me', 'arg1', 'arg2');
    125117 * </code>
    126118 *
    127119 * @package WordPress
    128120 * @subpackage Plugin
    129  * @since 1.5
     121 * @since 0.71
    130122 * @global array $wp_filter Stores all of the filters
    131123 * @global array $merge_filters Merges the filter hooks using this function.
     124 * @global array $wp_current_filter stores the list of current filters with the current one last
    132125 *
    133126 * @param string $tag The name of the filter hook.
    134  * @param string $value The value on which the filters hooked to <tt>$tag</tt> are applied on.
     127 * @param mixed $value The value on which the filters hooked to <tt>$tag</tt> are applied on.
    135128 * @param mixed $var,... Additional variables passed to the functions hooked to <tt>$tag</tt>.
    136  * @return string The text in <tt>$string</tt> after all hooked functions are applied to it.
     129 * @return mixed The filtered value after all hooked functions are applied to it.
    137130 */
    138131function apply_filters($tag, $value) {
    139132        global $wp_filter, $merged_filters, $wp_current_filter;
    140133
    141134        $args = array();
    142         @$wp_current_filter[] = $tag;
     135        $wp_current_filter[] = $tag;
    143136
    144137        // Do 'all' actions first
    145138        if ( isset($wp_filter['all']) ) {
    146                 reset( $wp_filter['all'] );
    147139                $args = func_get_args();
    148                 do {
    149                         foreach ( (array) current($wp_filter['all']) as $the_ )
    150                                 if ( !is_null($the_['function']) )
    151                                         call_user_func_array($the_['function'], $args);
    152 
    153                 } while ( next($wp_filter['all']) !== false );
     140                _wp_call_all_hook($args);
    154141        }
    155142
    156143        if ( !isset($wp_filter[$tag]) ) {
     
    160147
    161148        // Sort
    162149        if ( !isset( $merged_filters[ $tag ] ) ) {
    163                 reset($wp_filter[$tag]);
    164                 uksort($wp_filter[$tag], "strnatcasecmp");
     150                ksort($wp_filter[$tag]);
    165151                $merged_filters[ $tag ] = true;
    166152        }
    167153
     
    185171}
    186172
    187173/**
    188  * Removes a function from a specified filter hook.
     174 * remove_filter() - Removes a function from a specified filter hook.
    189175 *
    190176 * This function removes a function attached to a specified filter hook. This
    191177 * method can be used to remove default functions attached to a specific filter
     
    197183 *
    198184 * @package WordPress
    199185 * @subpackage Plugin
    200  * @since 1.5
     186 * @since 1.2
    201187 *
    202188 * @param string $tag The filter hook to which the function to be removed is hooked.
    203189 * @param callback $function_to_remove The name of the function which should be removed.
     
    222208
    223209
    224210/**
    225  * Return the name of the current filter or action.
     211 * current_filter() - Return the name of the current filter or action.
     212 *
     213 * @package WordPress
     214 * @subpackage Plugin
     215 * @since 2.4
     216 *
     217 * @return string Hook name of the current filter or action.
    226218 */
    227219function current_filter() {
    228220        global $wp_current_filter;
     
    231223
    232224
    233225/**
    234  * Hooks a function on to a specific action.
     226 * add_action() - Hooks a function on to a specific action.
    235227 *
    236228 * Actions are the hooks that the WordPress core launches at specific points
    237229 * during execution, or when specific events occur. Plugins can specify that
     
    242234 *
    243235 * @package WordPress
    244236 * @subpackage Plugin
    245  * @since 1.5
     237 * @since 1.2
    246238 *
    247239 * @param string $tag The name of the action to which the <tt>$function_to-add</tt> is hooked.
    248240 * @param callback $function_to_add The name of the function you wish to be called.
     
    250242 * @param int $accepted_args optional. The number of arguments the function accept (default 1).
    251243 */
    252244function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) {
    253         global $wp_filter, $merged_filters;
    254 
    255         $idx = _wp_filter_build_unique_id($tag, $function_to_add, $priority);
    256         $wp_filter[$tag][$priority][$idx] = array('function' => $function_to_add, 'accepted_args' => $accepted_args);
    257         unset( $merged_filters[ $tag ] );
    258         return true;
     245        return add_filter($tag, $function_to_add, $priority, $accepted_args);
    259246}
    260247
    261248
    262249/**
    263  * Execute functions hooked on a specific action hook.
     250 * do_action() - Execute functions hooked on a specific action hook.
    264251 *
    265252 * This function invokes all functions attached to action hook <tt>$tag</tt>.
    266253 * It is possible to create new action hooks by simply calling this function,
     
    273260 *
    274261 * @package WordPress
    275262 * @subpackage Plugin
    276  * @since 1.5
     263 * @since 1.2
    277264 * @global array $wp_filter Stores all of the filters
    278265 * @global array $wp_actions Increments the amount of times action was triggered.
    279266 *
     
    282269 * @return null Will return null if $tag does not exist in $wp_filter array
    283270 */
    284271function do_action($tag, $arg = '') {
    285         global $wp_filter, $wp_actions, $wp_current_filter;
     272        global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;
    286273
    287274        if ( is_array($wp_actions) )
    288275                $wp_actions[] = $tag;
    289276        else
    290277                $wp_actions = array($tag);
    291278
    292         @$wp_current_filter[] = $tag;
     279        $wp_current_filter[] = $tag;
    293280
    294281        // Do 'all' actions first
    295282        if ( isset($wp_filter['all']) ) {
    296                 reset( $wp_filter['all'] );
    297283                $all_args = func_get_args();
    298                 do {
    299                         foreach( (array) current($wp_filter['all']) as $the_ )
    300                                 if ( !is_null($the_['function']) )
    301                                         call_user_func_array($the_['function'], $all_args);
    302 
    303                 } while ( next($wp_filter['all']) !== false );
     284                _wp_call_all_hook($all_args);
    304285        }
    305286
    306287        if ( !isset($wp_filter[$tag]) ) {
     
    318299
    319300        // Sort
    320301        if ( !isset( $merged_filters[ $tag ] ) ) {
    321                 reset($wp_filter[$tag]);
    322                 uksort($wp_filter[$tag], "strnatcasecmp");
     302                ksort($wp_filter[$tag]);
    323303                $merged_filters[ $tag ] = true;
    324304        }
    325305
     
    332312
    333313        } while ( next($wp_filter[$tag]) !== false );
    334314
    335                 array_pop($wp_current_filter);
     315        array_pop($wp_current_filter);
    336316}
    337317
    338318/**
    339  * Return the number times an action is fired.
     319 * did_action() - Return the number times an action is fired.
    340320 *
    341321 * @package WordPress
    342322 * @subpackage Plugin
     
    356336}
    357337
    358338/**
    359  * Execute functions hooked on a specific action hook, specifying arguments in an array.
     339 * do_action_ref_array() - Execute functions hooked on a specific action hook, specifying arguments in an array.
    360340 *
    361341 * @see do_action() This function is identical, but the arguments passed to
    362342 * the functions hooked to <tt>$tag</tt> are supplied using an array.
     
    372352 * @return null Will return null if $tag does not exist in $wp_filter array
    373353 */
    374354function do_action_ref_array($tag, $args) {
    375         global $wp_filter, $wp_actions;
     355        global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;
    376356
    377357        if ( !is_array($wp_actions) )
    378358                $wp_actions = array($tag);
    379359        else
    380360                $wp_actions[] = $tag;
    381361
     362        $wp_current_filter[] = $tag;
     363
    382364        // Do 'all' actions first
    383365        if ( isset($wp_filter['all']) ) {
    384                 reset( $wp_filter['all'] );
    385366                $all_args = func_get_args();
    386                 do {
    387                         foreach( (array) current($wp_filter['all']) as $the_ )
    388                                 if ( !is_null($the_['function']) )
    389                                         call_user_func_array($the_['function'], $all_args);
    390 
    391                 } while ( next($wp_filter['all']) !== false );
     367                _wp_call_all_hook($all_args);
    392368        }
    393369
    394         if ( !isset($wp_filter[$tag]) )
     370        if ( !isset($wp_filter[$tag]) ) {
     371                array_pop($wp_current_filter);
    395372                return;
     373        }
    396374
    397375        // Sort
    398376        if ( !isset( $merged_filters[ $tag ] ) ) {
    399                 reset($wp_filter[$tag]);
    400                 uksort($wp_filter[$tag], "strnatcasecmp");
     377                ksort($wp_filter[$tag]);
    401378                $merged_filters[ $tag ] = true;
    402379        }
    403380
     
    410387
    411388        } while ( next($wp_filter[$tag]) !== false );
    412389
     390        array_pop($wp_current_filter);
    413391}
    414392
    415393/**
    416  * Check if any action has been registered for a hook.  Optionally returns the priority on that hook for the specified function.
     394 * has_action() - Check if any action has been registered for a hook.
     395 *
    417396 * @package WordPress
    418397 * @subpackage Plugin
    419398 * @since 2.4
    420  * @global array $wp_filter Stores all of the actions
     399 * @see has_filter() has_action() is an alias of has_filter().
    421400 *
    422401 * @param string $tag The name of the action hook.
    423402 * @param callback $function_to_check optional.  If specified, return the priority of that function on this hook or false if not attached.
    424  * @return int|boolean
     403 * @return int|boolean Optionally returns the priority on that hook for the specified function.
    425404 */
    426405function has_action($tag, $function_to_check = false) {
    427406        return has_filter($tag, $function_to_check);
    428407}
    429408
    430409/**
    431  * Removes a function from a specified action hook.
     410 * remove_action() - Removes a function from a specified action hook.
    432411 *
    433412 * This function removes a function attached to a specified action hook. This
    434413 * method can be used to remove default functions attached to a specific filter
     
    436415 *
    437416 * @package WordPress
    438417 * @subpackage Plugin
    439  * @since 1.5
     418 * @since 1.2
    440419 *
    441420 * @param string $tag The action hook to which the function to be removed is hooked.
    442421 * @param callback $function_to_remove The name of the function which should be removed.
     
    453432//
    454433
    455434/**
    456  * Gets the basename of a plugin.
     435 * plugin_basename() - Gets the basename of a plugin.
    457436 *
    458437 * This method extract the name of a plugin from its filename.
    459438 *
     
    474453}
    475454
    476455/**
    477  * Hook a function on a plugin activation action hook.
     456 * register_activation_hook() - Hook a function on a plugin activation action hook.
    478457 *
    479458 * When a plugin is activated, the action 'activate_PLUGINNAME' hook is
    480459 * activated. In the name of this hook, PLUGINNAME is replaced with the name of
     
    487466 *
    488467 * @package WordPress
    489468 * @subpackage Plugin
    490  * @since 1.5
     469 * @since 2.0
    491470 *
    492471 * @access private
    493472 *
     
    500479}
    501480
    502481/**
    503  * Hook a function on a plugin deactivation action hook.
     482 * register_deactivation_hook() - Hook a function on a plugin deactivation action hook.
    504483 *
    505484 * When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is
    506485 * deactivated. In the name of this hook, PLUGINNAME is replaced with the name of
     
    525504        add_action('deactivate_' . $file, $function);
    526505}
    527506
     507/**
     508 * _wp_call_all_hook() - Calls the 'all' hook, which will process the functions hooked into it.
     509 *
     510 * The 'all' hook passes all of the arguments or parameters that were used for the
     511 * hook, which this function was called for. The first parameter will have to be tested
     512 * as it will be the hook name.
     513 *
     514 * This function is used internally for apply_filters(), do_action(), and do_action_ref_array()
     515 * and is not meant to be used from outside those functions. This function does not check for the
     516 * existent of the all hook, so it will fail unless the all hook exists prior to this function call.
     517 *
     518 * @package WordPress
     519 * @subpackage Plugin
     520 * @since 2.4
     521 * @access private
     522 *
     523 * @uses $wp_filter Used to process all of the functions in the 'all' hook
     524 *
     525 * @param array $args The collected parameters from the hook that was called.
     526 * @param string $hook Optional. The hook name that was used to call the 'all' hook.
     527 */
     528function _wp_call_all_hook($args) {
     529        global $wp_filter;
     530
     531        reset( $wp_filter['all'] );
     532        do {
     533                foreach( (array) current($wp_filter['all']) as $the_ )
     534                        if ( !is_null($the_['function']) )
     535                                call_user_func_array($the_['function'], $args);
     536
     537        } while ( next($wp_filter['all']) !== false );
     538}
     539
    528540/**
    529  * Build Unique ID for storage and retrieval
     541 * _wp_filter_build_unique_id() - Build Unique ID for storage and retrieval
    530542 *
    531543 * The old way to serialize the callback caused issues and this function is the
    532544 * solution. It works by checking for objects and creating an a new property in
     
    557569 * @param string $type filter or action
    558570 * @return string Unique ID for usage as array key
    559571 */
    560 function _wp_filter_build_unique_id($tag, $function, $priority)
    561 {
     572function _wp_filter_build_unique_id($tag, $function, $priority) {
    562573        global $wp_filter;
    563574
    564575        // If function then just skip all of the tests and not overwrite the following.