WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
12/06/2007 05:56:38 AM (17 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.