WordPress.org

Make WordPress Core

Changeset 46801


Ignore:
Timestamp:
11/29/2019 09:40:58 PM (12 months ago)
Author:
SergeyBiryukov
Message:

Docs: Correct @param type for the function parameter in tests_add_filter() and _test_filter_build_unique_id().

Synchronize documentation for add_filter(), tests_add_filter(), _wp_filter_build_unique_id(), _test_filter_build_unique_id().

Add a note that $tag and $priority are no longer used in _wp_filter_build_unique_id() since [46220], and the function always returns a string now.

Props donmhico, remcotolsma, SergeyBiryukov.
Fixes #47407. See #48303.

Location:
trunk
Files:
3 edited

Legend:

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

    r46586 r46801  
    6565     * @param string   $tag             The name of the filter to hook the $function_to_add callback to.
    6666     * @param callable $function_to_add The callback to be run when the filter is applied.
    67      * @param int      $priority        The order in which the functions associated with a
    68      *                                  particular action are executed. Lower numbers correspond with
    69      *                                  earlier execution, and functions with the same priority are executed
    70      *                                  in the order in which they were added to the action.
     67     * @param int      $priority        The order in which the functions associated with a particular action
     68     *                                  are executed. Lower numbers correspond with earlier execution,
     69     *                                  and functions with the same priority are executed in the order
     70     *                                  in which they were added to the action.
    7171     * @param int      $accepted_args   The number of arguments the function accepts.
    7272     */
    7373    public function add_filter( $tag, $function_to_add, $priority, $accepted_args ) {
    74         $idx              = _wp_filter_build_unique_id( $tag, $function_to_add, $priority );
     74        $idx = _wp_filter_build_unique_id( $tag, $function_to_add, $priority );
     75
    7576        $priority_existed = isset( $this->callbacks[ $priority ] );
    7677
     
    163164     * @since 4.7.0
    164165     *
    165      * @param string   $tag                The filter hook to which the function to be removed is hooked. Used
    166      *                                     for building the callback ID when SPL is not available.
     166     * @param string   $tag                The filter hook to which the function to be removed is hooked.
    167167     * @param callable $function_to_remove The callback to be removed from running when the filter is applied.
    168168     * @param int      $priority           The exact priority used when adding the original filter callback.
     
    190190     * @since 4.7.0
    191191     *
    192      * @param string        $tag               Optional. The name of the filter hook. Used for building
    193      *                                         the callback ID when SPL is not available. Default empty.
     192     * @param string        $tag               Optional. The name of the filter hook. Default empty.
    194193     * @param callable|bool $function_to_check Optional. The callback to check for. Default false.
    195194     * @return bool|int The priority of that hook is returned, or false if the function is not attached.
  • trunk/src/wp-includes/plugin.php

    r46792 r46801  
    9494 * @since 0.71
    9595 *
    96  * @global array $wp_filter      A multidimensional array of all hooks and the callbacks hooked to them.
     96 * @global array $wp_filter A multidimensional array of all hooks and the callbacks hooked to them.
    9797 *
    9898 * @param string   $tag             The name of the filter to hook the $function_to_add callback to.
    9999 * @param callable $function_to_add The callback to be run when the filter is applied.
    100100 * @param int      $priority        Optional. Used to specify the order in which the functions
    101  *                                  associated with a particular action are executed. Default 10.
     101 *                                  associated with a particular action are executed.
    102102 *                                  Lower numbers correspond with earlier execution,
    103103 *                                  and functions with the same priority are executed
    104  *                                  in the order in which they were added to the action.
     104 *                                  in the order in which they were added to the action. Default 10.
    105105 * @param int      $accepted_args   Optional. The number of arguments the function accepts. Default 1.
    106106 * @return true
     
    120120 * @since 2.5.0
    121121 *
    122  * @global array $wp_filter Stores all of the filters.
     122 * @global array $wp_filter Stores all of the filters and actions.
    123123 *
    124124 * @param string        $tag               The name of the filter hook.
     
    171171 * @since 0.71
    172172 *
    173  * @global array $wp_filter         Stores all of the filters.
     173 * @global array $wp_filter         Stores all of the filters and actions.
    174174 * @global array $wp_current_filter Stores the list of current filters with the current one last.
    175175 *
     
    219219 * functions hooked to `$tag` are supplied using an array.
    220220 *
    221  * @global array $wp_filter         Stores all of the filters
    222  * @global array $wp_current_filter Stores the list of current filters with the current one last
     221 * @global array $wp_filter         Stores all of the filters and actions.
     222 * @global array $wp_current_filter Stores the list of current filters with the current one last.
    223223 *
    224224 * @param string $tag  The name of the filter hook.
     
    267267 * @since 1.2.0
    268268 *
    269  * @global array $wp_filter         Stores all of the filters
     269 * @global array $wp_filter Stores all of the filters and actions.
    270270 *
    271271 * @param string   $tag                The filter hook to which the function to be removed is hooked.
     
    293293 * @since 2.7.0
    294294 *
    295  * @global array $wp_filter  Stores all of the filters
     295 * @global array $wp_filter Stores all of the filters and actions.
    296296 *
    297297 * @param string   $tag      The filter to remove hooks from.
     
    434434 *              by adding it to the function signature.
    435435 *
    436  * @global array $wp_filter         Stores all of the filters
     436 * @global array $wp_filter         Stores all of the filters and actions.
    437437 * @global array $wp_actions        Increments the amount of times action was triggered.
    438  * @global array $wp_current_filter Stores the list of current filters with the current one last
     438 * @global array $wp_current_filter Stores the list of current filters with the current one last.
    439439 *
    440440 * @param string $tag    The name of the action to be executed.
     
    508508 * @see do_action() This function is identical, but the arguments passed to the
    509509 *                  functions hooked to `$tag` are supplied using an array.
    510  * @global array $wp_filter         Stores all of the filters
     510 * @global array $wp_filter         Stores all of the filters and actions.
    511511 * @global array $wp_actions        Increments the amount of times action was triggered.
    512  * @global array $wp_current_filter Stores the list of current filters with the current one last
     512 * @global array $wp_current_filter Stores the list of current filters with the current one last.
    513513 *
    514514 * @param string $tag  The name of the action to be executed.
     
    868868 * @access private
    869869 *
    870  * @global array $wp_filter  Stores all of the filters
     870 * @global array $wp_filter Stores all of the filters and actions.
    871871 *
    872872 * @param array $args The collected parameters from the hook that was called.
     
    898898 *
    899899 * @since 2.2.3
     900 * @since 5.3.0 Removed workarounds for spl_object_hash().
     901 *              `$tag` and `$priority` are no longer used,
     902 *              and the function always returns a string.
    900903 * @access private
    901904 *
    902  * @global array $wp_filter Storage for all of the filters and actions.
     905 * @global array $wp_filter Stores all of the filters and actions.
    903906 * @staticvar int $filter_id_count
    904907 *
    905  * @param string   $tag      Used in counting how many hooks were applied
    906  * @param callable $function Used for creating unique id
    907  * @param int|bool $priority Used in counting how many hooks were applied. If === false
    908  *                           and $function is an object reference, we return the unique
    909  *                           id only if it already has one, false otherwise.
    910  * @return string|false Unique ID for usage as array key or false if $priority === false
    911  *                      and $function is an object reference, and it does not already have
    912  *                      a unique id.
     908 * @param string   $tag      Unused. The name of the filter to build ID for.
     909 * @param callable $function The function to generate ID for.
     910 * @param int      $priority Unused. The order in which the functions associated
     911 *                           with a particular action are executed.
     912 * @return string Unique ID for usage as array key.
    913913 */
    914914function _wp_filter_build_unique_id( $tag, $function, $priority ) {
     
    921921
    922922    if ( is_object( $function ) ) {
    923         // Closures are currently implemented as objects
     923        // Closures are currently implemented as objects.
    924924        $function = array( $function, '' );
    925925    } else {
     
    928928
    929929    if ( is_object( $function[0] ) ) {
    930         // Object Class Calling
     930        // Object class calling.
    931931        return spl_object_hash( $function[0] ) . $function[1];
    932932    } elseif ( is_string( $function[0] ) ) {
    933         // Static Calling
     933        // Static calling.
    934934        return $function[0] . '::' . $function[1];
    935935    }
  • trunk/tests/phpunit/includes/functions.php

    r46586 r46801  
    3939 * Adds hooks before loading WP.
    4040 *
    41  * @param string       $tag             The name for the filter to add.
    42  * @param object|array $function_to_add The function/callback to execute on call.
    43  * @param int          $priority        The priority.
    44  * @param int          $accepted_args   The amount of accepted arguments.
    45  * @return bool Always true.
     41 * @see add_filter()
     42 *
     43 * @param string   $tag             The name of the filter to hook the $function_to_add callback to.
     44 * @param callable $function_to_add The callback to be run when the filter is applied.
     45 * @param int      $priority        Optional. Used to specify the order in which the functions
     46 *                                  associated with a particular action are executed.
     47 *                                  Lower numbers correspond with earlier execution,
     48 *                                  and functions with the same priority are executed
     49 *                                  in the order in which they were added to the action. Default 10.
     50 * @param int      $accepted_args   Optional. The number of arguments the function accepts. Default 1.
     51 * @return true
    4652 */
    4753function tests_add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
     
    5157        add_filter( $tag, $function_to_add, $priority, $accepted_args );
    5258    } else {
    53         $idx                                    = _test_filter_build_unique_id( $tag, $function_to_add, $priority );
     59        $idx = _test_filter_build_unique_id( $tag, $function_to_add, $priority );
     60
    5461        $wp_filter[ $tag ][ $priority ][ $idx ] = array(
    5562            'function'      => $function_to_add,
     
    6370 * Generates a unique function ID based on the given arguments.
    6471 *
    65  * @param string       $tag      Unused. The name of the filter to build ID for.
    66  * @param object|array $function The function to generate ID for.
    67  * @param int          $priority Unused. The priority.
    68  * @return string Unique function ID.
     72 * @see _wp_filter_build_unique_id()
     73 *
     74 * @param string   $tag      Unused. The name of the filter to build ID for.
     75 * @param callable $function The function to generate ID for.
     76 * @param int      $priority Unused. The order in which the functions
     77 *                           associated with a particular action are executed.
     78 * @return string Unique function ID for usage as array key.
    6979 */
    7080function _test_filter_build_unique_id( $tag, $function, $priority ) {
     
    8191
    8292    if ( is_object( $function[0] ) ) {
     93        // Object class calling.
    8394        return spl_object_hash( $function[0] ) . $function[1];
    8495    } elseif ( is_string( $function[0] ) ) {
    85         // Static Calling.
     96        // Static calling.
    8697        return $function[0] . $function[1];
    8798    }
Note: See TracChangeset for help on using the changeset viewer.