WordPress.org

Make WordPress Core

Ticket #5338: plugin.r6334.patch

File plugin.r6334.patch, 14.5 KB (added by darkdragon, 8 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.