WordPress.org

Make WordPress Core

Ticket #19203: 19203.diff

File 19203.diff, 3.7 KB (added by DrewAPicture, 8 months ago)
  • 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 uses filter hooks to make it possible to modify data of various types 
     26 * before it is added to the database and/or sent to the browser screen. 
    2927 * 
    30  * To use the API, the following code should be used to bind a callback to the 
    31  * filter. 
     28 * Using the Plugin API, a plugin can modify data via these filter hooks by assigning 
     29 * one or more of its PHP functions to be used as a "callback". When a filter hook 
     30 * is later evaluated, each callback function is run against that value in order of 
     31 * priority until all callback functions have run their course. 
    3232 * 
     33 * The following example shows how a callback function is bound to a filter hook. 
     34 * Note that $example is passed to the callback, (maybe) modified, then returned: 
     35 * 
    3336 * <code> 
    34  * function example_hook($example) { echo $example; } 
    35  * add_filter('example_filter', 'example_hook'); 
     37 * function example_callback( $example ) { 
     38 *      // Maybe modify $example in some way 
     39 *      return $example 
     40 * } 
     41 * add_filter( 'example_filter', 'example_callback' ); 
    3642 * </code> 
    3743 * 
    3844 * In WordPress 1.5.1+, hooked functions can take extra arguments that are set 
    3945 * 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 
     46 * $accepted_args parameter allows for calling functions only when the number of args 
    4147 * 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. 
     48 * matching do_action() or apply_filters() call is run. For example, the comment_id_not_found 
     49 * action will pass any functions that hook onto it the ID of the requested comment. 
    4550 * 
    4651 * <strong>Note:</strong> the function will return true no matter if the 
    4752 * function was hooked fails or not. There are no checks for whether the 
     
    114119 * 
    115120 * The function allows for additional arguments to be added and passed to hooks. 
    116121 * <code> 
    117  * function example_hook($string, $arg1, $arg2) 
    118  * { 
    119  *              //Do stuff 
    120  *              return $string; 
     122 * // Our filter callback function 
     123 * function example_callback( $string, $arg1, $arg2 ) { 
     124 *      // Maybe modify $string 
     125 *      return $string; 
    121126 * } 
    122  * $value = apply_filters('example_filter', 'filter me', 'arg1', 'arg2'); 
     127 * add_filter( 'example_filter', 'example_callback', 10, 3 ); 
     128 * 
     129 * // Apply the filters by calling the 'example_callback' function we 
     130 * // "hooked" to 'example_filter' using the add_filter() function above. 
     131 * // - 'example_filter' is the filter hook $tag 
     132 * // - 'filter me' is the value being filtered 
     133 * // - $arg1 and $arg2 are the additional arguments passed to the callback. 
     134 * $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 ); 
    123135 * </code> 
    124136 * 
    125137 * @package WordPress 
     
    708720 * @uses $wp_filter Used to process all of the functions in the 'all' hook 
    709721 * 
    710722 * @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. 
    712723 */ 
    713724function _wp_call_all_hook($args) { 
    714725        global $wp_filter;