WordPress.org

Make WordPress Core

Ticket #19203: 19203.diff

File 19203.diff, 3.7 KB (added by DrewAPicture, 5 years 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;