Filter hook 'example_filter'

Description

Adds a callback function to a filter hook. WordPress offers filter hooks to allow plugins to modify various types of internal data at runtime. A plugin can modify data by binding a callback to a filter hook. When the filter is later applied, each bound callback is run in order of priority, and given the opportunity to modify a value by returning a new value. The following example shows how a callback function is bound to a filter hook. Note that `$example` is passed to the callback, (maybe) modified, then returned: function example_callback( $example ) { // Maybe modify $example in some way. return $example; } add_filter( 'example_filter', 'example_callback' ); Bound callbacks can accept from none to the total number of arguments passed as parameters in the corresponding apply_filters() call. In other words, if an apply_filters() call passes four total arguments, callbacks bound to it can accept none (the same as 1) of the arguments or up to four. The important part is that the `$accepted_args` value must reflect the number of arguments the bound callback *actually* opted to accept. If no arguments were accepted by the callback that is considered to be the same as accepting 1 argument. For example: // Filter call. $value = apply_filters( 'hook', $value, $arg2, $arg3 ); // Accepting zero/one arguments. function example_callback() { ... return 'some value'; } add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1. // Accepting two arguments (three possible). function example_callback( $value, $arg2 ) { ... return $maybe_modified_value; } add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2. *Note:* The function will return true whether or not the callback is valid. It is up to you to take care. This is done for optimization purposes, so everything is as quick as possible.

Occurrences

Parameters

Usage Examples

Example 1

add_filter( 'example_filter', 'example_callback'

Example 2

add_filter( 'example_filter', 'example_callback'

PHP Doc

/**
 * Adds a callback function to a filter hook.
 *
 * WordPress offers filter hooks to allow plugins to modify
 * various types of internal data at runtime.
 *
 * A plugin can modify data by binding a callback to a filter hook. When the filter
 * is later applied, each bound callback is run in order of priority, and given
 * the opportunity to modify a value by returning a new value.
 *
 * The following example shows how a callback function is bound to a filter hook.
 *
 * Note that `$example` is passed to the callback, (maybe) modified, then returned:
 *
 *     function example_callback( $example ) {
 *         // Maybe modify $example in some way.
 *         return $example;
 *     }
 *     add_filter( 'example_filter', 'example_callback' );
 *
 * Bound callbacks can accept from none to the total number of arguments passed as parameters
 * in the corresponding apply_filters() call.
 *
 * In other words, if an apply_filters() call passes four total arguments, callbacks bound to
 * it can accept none (the same as 1) of the arguments or up to four. The important part is that
 * the `$accepted_args` value must reflect the number of arguments the bound callback *actually*
 * opted to accept. If no arguments were accepted by the callback that is considered to be the
 * same as accepting 1 argument. For example:
 *
 *     // Filter call.
 *     $value = apply_filters( 'hook', $value, $arg2, $arg3 );
 *
 *     // Accepting zero/one arguments.
 *     function example_callback() {
 *         ...
 *         return 'some value';
 *     }
 *     add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1.
 *
 *     // Accepting two arguments (three possible).
 *     function example_callback( $value, $arg2 ) {
 *         ...
 *         return $maybe_modified_value;
 *     }
 *     add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2.
 *
 * *Note:* The function will return true whether or not the callback is valid.
 * It is up to you to take care. This is done for optimization purposes, so
 * everything is as quick as possible.
 *
 * @since 0.71
 *
 * @global WP_Hook[] $wp_filter A multidimensional array of all hooks and the callbacks hooked to them.
 *
 * @param string   $hook_name     The name of the filter to add the callback to.
 * @param callable $callback      The callback to be run when the filter is applied.
 * @param int      $priority      Optional. Used to specify the order in which the functions
 *                                associated with a particular filter 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 filter. Default 10.
 * @param int      $accepted_args Optional. The number of arguments the function accepts. Default 1.
 * @return true Always returns true.
 */