WordPress.org

Make WordPress Core

Changeset 34288


Ignore:
Timestamp:
09/18/2015 02:52:37 PM (4 years ago)
Author:
DrewAPicture
Message:

Docs: Clarify the significance of the $accepted_args parameter value in the documentation for add_filter().

Adds a couple of examples to illustrate callbacks accepting a variable number of arguments.

Fixes #33862.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/plugin.php

    r33734 r34288  
    5555 *     add_filter( 'example_filter', 'example_callback' );
    5656 *
    57  * Since WordPress 1.5.1, bound callbacks can take as many arguments as are
    58  * passed as parameters in the corresponding apply_filters() call. The `$accepted_args`
    59  * parameter allows for calling functions only when the number of args match.
    60  *
    61  * *Note:* the function will return true whether or not the callback is valid.
    62  * It is up to you to take care. This is done for optimization purposes,
    63  * so everything is as quick as possible.
     57 * Bound callbacks can accept from none to the total number of arguments passed as parameters
     58 * in the corresponding apply_filters() call.
     59 *
     60 * In other words, if an apply_filters() call passes four total arguments, callbacks bound to
     61 * it can accept none (the same as 1) of the arguments or up to four. The important part is that
     62 * the `$accepted_args` value must reflect the number of arguments the bound callback *actually*
     63 * opted to accept. If no arguments were accepted by the callback that is considered to be the
     64 * same as accepting 1 argument. For example:
     65 *
     66 *     // Filter call.
     67 *     $value = apply_filters( 'hook', $value, $arg2, $arg3 );
     68 *
     69 *     // Accepting zero/one arguments.
     70 *     function example_callback() {
     71 *         ...
     72 *         return 'some value';
     73 *     }
     74 *     add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1.
     75 *
     76 *     // Accepting two arguments (three possible).
     77 *     function example_callback( $value, $arg2 ) {
     78 *         ...
     79 *         return $maybe_modified_value;
     80 *     }
     81 *     add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2.
     82 *
     83 * *Note:* The function will return true whether or not the callback is valid.
     84 * It is up to you to take care. This is done for optimization purposes, so
     85 * everything is as quick as possible.
    6486 *
    6587 * @since 0.71
Note: See TracChangeset for help on using the changeset viewer.