WordPress.org

Make WordPress Core

Ticket #19203: 19203.4.diff

File 19203.4.diff, 7.1 KB (added by DrewAPicture, 19 months ago)
  • src/wp-includes/plugin.php

     
    2222/** 
    2323 * Hooks a function or method to a specific filter action. 
    2424 * 
    25  * Filters are the hooks that WordPress launches to modify text of various types 
    26  * before adding it to the database or sending it to the browser screen. Plugins 
    27  * can specify that one or more of its PHP functions is executed to 
    28  * modify specific types of text at these times, using the Filter API. 
     25 * WordPress offers filter hooks to allow plugins to modify 
     26 * various types of internal data at runtime. 
    2927 * 
    30  * To use the API, the following code should be used to bind a callback to the 
    31  * filter. 
     28 * A plugin can modify data by binding a callback to a filter hook. When the filter 
     29 * is later applied, each bound callback is run in order of priority, and given 
     30 * the opportunity to modify a value by returning a new value. 
    3231 * 
     32 * The following example shows how a callback function is bound to a filter hook. 
     33 * Note that $example is passed to the callback, (maybe) modified, then returned: 
     34 * 
    3335 * <code> 
    34  * function example_hook($example) { echo $example; } 
    35  * add_filter('example_filter', 'example_hook'); 
     36 * function example_callback( $example ) { 
     37 *      // Maybe modify $example in some way 
     38 *      return $example; 
     39 * } 
     40 * add_filter( 'example_filter', 'example_callback' ); 
    3641 * </code> 
    3742 * 
    38  * In WordPress 1.5.1+, hooked functions can take extra arguments that are set 
    39  * when the matching do_action() or apply_filters() call is run. The 
    40  * $accepted_args allow for calling functions only when the number of args 
    41  * match. Hooked functions can take extra arguments that are set when the 
    42  * matching do_action() or apply_filters() call is run. For example, the action 
    43  * comment_id_not_found will pass any functions that hook onto it the ID of the 
    44  * requested comment. 
     43 * Since WordPress 1.5.1, bound callbacks can take as many arguments as are 
     44 * passed as parameters in the corresponding apply_filters() call. The $accepted_args 
     45 * parameter allows for calling functions only when the number of args match. 
    4546 * 
    46  * <strong>Note:</strong> the function will return true no matter if the 
    47  * function was hooked fails or not. There are no checks for whether the 
    48  * function exists beforehand and no checks to whether the <tt>$function_to_add</tt> 
    49  * is even a string. It is up to you to take care and this is done for 
    50  * optimization purposes, so everything is as quick as possible. 
     47 * <strong>Note:</strong> the function will return true whether or not the callback 
     48 * is valid. It is up to you to take care. This is done for optimization purposes, 
     49 * so everything is as quick as possible. 
    5150 * 
    5251 * @package WordPress 
    5352 * @subpackage Plugin 
    54  * @since 0.71 
    55  * @global array $wp_filter Stores all of the filters added in the form of 
    56  *      wp_filter['tag']['array of priorities']['array of functions serialized']['array of ['array (functions, accepted_args)']'] 
     53 * 
     54 * @global array $wp_filter      A multidimensional array of all hooks and the callbacks hooked to them. 
    5755 * @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. 
    5856 * 
    59  * @param string $tag The name of the filter to hook the $function_to_add to. 
    60  * @param callback $function_to_add The name of the function to be called when the filter is applied. 
    61  * @param int $priority optional. Used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action. 
    62  * @param int $accepted_args optional. The number of arguments the function accept (default 1). 
     57 * @since 0.71 
     58 * 
     59 * @param string   $tag             The name of the filter to hook the $function_to_add callback to. 
     60 * @param callback $function_to_add The callback to be run when the filter is applied. 
     61 * @param int      $priority        (optional) The order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action. 
     62 *                                  Default 10. 
     63 * @param int      $accepted_args   (optional) The number of arguments the function accepts. 
     64 *                                  Default 1. 
    6365 * @return boolean true 
    6466 */ 
    65 function add_filter($tag, $function_to_add, $priority = 10, $accepted_args = 1) { 
     67function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) { 
    6668        global $wp_filter, $merged_filters; 
    6769 
    6870        $idx = _wp_filter_build_unique_id($tag, $function_to_add, $priority); 
     
    114116 * 
    115117 * The function allows for additional arguments to be added and passed to hooks. 
    116118 * <code> 
    117  * function example_hook($string, $arg1, $arg2) 
    118  * { 
    119  *              //Do stuff 
    120  *              return $string; 
     119 * // Our filter callback function 
     120 * function example_callback( $string, $arg1, $arg2 ) { 
     121 *      // (maybe) modify $string 
     122 *      return $string; 
    121123 * } 
    122  * $value = apply_filters('example_filter', 'filter me', 'arg1', 'arg2'); 
     124 * add_filter( 'example_filter', 'example_callback', 10, 3 ); 
     125 * 
     126 * // Apply the filters by calling the 'example_callback' function we 
     127 * // "hooked" to 'example_filter' using the add_filter() function above. 
     128 * // - 'example_filter' is the filter hook $tag 
     129 * // - 'filter me' is the value being filtered 
     130 * // - $arg1 and $arg2 are the additional arguments passed to the callback. 
     131 * $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 ); 
    123132 * </code> 
    124133 * 
    125134 * @package WordPress 
    126135 * @subpackage Plugin 
    127  * @since 0.71 
    128  * @global array $wp_filter Stores all of the filters 
    129  * @global array $merged_filters Merges the filter hooks using this function. 
     136 * 
     137 * @global array $wp_filter         Stores all of the filters 
     138 * @global array $merged_filters    Merges the filter hooks using this function. 
    130139 * @global array $wp_current_filter stores the list of current filters with the current one last 
    131140 * 
    132  * @param string $tag The name of the filter hook. 
     141 * @since 0.71 
     142 * 
     143 * @param string $tag  The name of the filter hook. 
    133144 * @param mixed $value The value on which the filters hooked to <tt>$tag</tt> are applied on. 
    134  * @param mixed $var,... Additional variables passed to the functions hooked to <tt>$tag</tt>. 
     145 * @param mixed $var  Additional variables passed to the functions hooked to <tt>$tag</tt>. 
    135146 * @return mixed The filtered value after all hooked functions are applied to it. 
    136147 */ 
    137 function apply_filters($tag, $value) { 
     148function apply_filters( $tag, $value ) { 
    138149        global $wp_filter, $merged_filters, $wp_current_filter; 
    139150 
    140151        $args = array(); 
     
    708719 * @uses $wp_filter Used to process all of the functions in the 'all' hook 
    709720 * 
    710721 * @param array $args The collected parameters from the hook that was called. 
    711  * @param string $hook Optional. The hook name that was used to call the 'all' hook. 
    712722 */ 
    713723function _wp_call_all_hook($args) { 
    714724        global $wp_filter;