WordPress.org

Make WordPress Core

Changeset 6361


Ignore:
Timestamp:
12/06/07 05:56:38 (8 years ago)
Author:
ryan
Message:

Filter and action optimizations and phpdoc updates from darkdragon. fixes #5338

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/plugin.php

    r6324 r6361  
    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 
     
    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 
     
    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)]'] 
     
    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 
     
    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) { 
     
    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 
     
    121112 * { 
    122113 *      //Do stuff 
     114 *      return $string; 
    123115 * } 
    124116 * $value = apply_filters('example_filter', 'filter me', 'arg1', 'arg2'); 
     
    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) { 
     
    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 
     
    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    } 
     
    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 
     
    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. 
     
    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() { 
     
    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 
     
    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. 
     
    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; 
    259 } 
    260  
    261  
    262 /** 
    263  * Execute functions hooked on a specific action hook. 
     245    return add_filter($tag, $function_to_add, $priority, $accepted_args); 
     246} 
     247 
     248 
     249/** 
     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>. 
     
    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. 
     
    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) ) 
     
    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 
     
    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    } 
     
    333313    } while ( next($wp_filter[$tag]) !== false ); 
    334314 
    335         array_pop($wp_current_filter); 
    336 } 
    337  
    338 /** 
    339  * Return the number times an action is fired. 
     315    array_pop($wp_current_filter); 
     316} 
     317 
     318/** 
     319 * did_action() - Return the number times an action is fired. 
    340320 * 
    341321 * @package WordPress 
     
    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 
     
    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) ) 
     
    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 ); 
    392     } 
    393  
    394     if ( !isset($wp_filter[$tag]) ) 
     367        _wp_call_all_hook($all_args); 
     368    } 
     369 
     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    } 
     
    411388    } while ( next($wp_filter[$tag]) !== false ); 
    412389 
    413 } 
    414  
    415 /** 
    416  * Check if any action has been registered for a hook.  Optionally returns the priority on that hook for the specified function. 
     390    array_pop($wp_current_filter); 
     391} 
     392 
     393/** 
     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) { 
     
    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 
     
    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. 
     
    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. 
     
    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 
     
    488467 * @package WordPress 
    489468 * @subpackage Plugin 
    490  * @since 1.5 
     469 * @since 2.0 
    491470 * 
    492471 * @access private 
     
    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 
     
    526505} 
    527506 
    528 /** 
    529  * Build Unique ID for storage and retrieval 
     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 
     540/** 
     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 
     
    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 
Note: See TracChangeset for help on using the changeset viewer.