From 890bd870e8867a0eefab0b20c31669f59167be07 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Fri, 29 Nov 2019 21:40:58 +0000 Subject: [PATCH] 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. git-svn-id: https://develop.svn.wordpress.org/trunk@46801 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/class-wp-hook.php | 17 +++++---- src/wp-includes/plugin.php | 52 ++++++++++++++-------------- tests/phpunit/includes/functions.php | 33 ++++++++++++------ 3 files changed, 56 insertions(+), 46 deletions(-) diff --git a/src/wp-includes/class-wp-hook.php b/src/wp-includes/class-wp-hook.php index abae430a9e..1ee13bae86 100644 --- a/src/wp-includes/class-wp-hook.php +++ b/src/wp-includes/class-wp-hook.php @@ -64,14 +64,15 @@ final class WP_Hook implements Iterator, ArrayAccess { * * @param string $tag The name of the filter to hook the $function_to_add callback to. * @param callable $function_to_add The callback to be run when the filter is applied. - * @param int $priority The order in which the functions associated with a - * particular action 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 action. + * @param int $priority The order in which the functions associated with a particular action + * 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 action. * @param int $accepted_args The number of arguments the function accepts. */ public function add_filter( $tag, $function_to_add, $priority, $accepted_args ) { - $idx = _wp_filter_build_unique_id( $tag, $function_to_add, $priority ); + $idx = _wp_filter_build_unique_id( $tag, $function_to_add, $priority ); + $priority_existed = isset( $this->callbacks[ $priority ] ); $this->callbacks[ $priority ][ $idx ] = array( @@ -162,8 +163,7 @@ final class WP_Hook implements Iterator, ArrayAccess { * * @since 4.7.0 * - * @param string $tag The filter hook to which the function to be removed is hooked. Used - * for building the callback ID when SPL is not available. + * @param string $tag The filter hook to which the function to be removed is hooked. * @param callable $function_to_remove The callback to be removed from running when the filter is applied. * @param int $priority The exact priority used when adding the original filter callback. * @return bool Whether the callback existed before it was removed. @@ -189,8 +189,7 @@ final class WP_Hook implements Iterator, ArrayAccess { * * @since 4.7.0 * - * @param string $tag Optional. The name of the filter hook. Used for building - * the callback ID when SPL is not available. Default empty. + * @param string $tag Optional. The name of the filter hook. Default empty. * @param callable|bool $function_to_check Optional. The callback to check for. Default false. * @return bool|int The priority of that hook is returned, or false if the function is not attached. */ diff --git a/src/wp-includes/plugin.php b/src/wp-includes/plugin.php index 66d2379655..ead5253404 100644 --- a/src/wp-includes/plugin.php +++ b/src/wp-includes/plugin.php @@ -93,15 +93,15 @@ if ( ! isset( $wp_current_filter ) ) { * * @since 0.71 * - * @global array $wp_filter A multidimensional array of all hooks and the callbacks hooked to them. + * @global array $wp_filter A multidimensional array of all hooks and the callbacks hooked to them. * * @param string $tag The name of the filter to hook the $function_to_add callback to. * @param callable $function_to_add 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 action are executed. Default 10. + * associated with a particular action 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 action. + * in the order in which they were added to the action. Default 10. * @param int $accepted_args Optional. The number of arguments the function accepts. Default 1. * @return true */ @@ -119,7 +119,7 @@ function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 * * @since 2.5.0 * - * @global array $wp_filter Stores all of the filters. + * @global array $wp_filter Stores all of the filters and actions. * * @param string $tag The name of the filter hook. * @param callable|bool $function_to_check Optional. The callback to check for. Default false. @@ -170,7 +170,7 @@ function has_filter( $tag, $function_to_check = false ) { * * @since 0.71 * - * @global array $wp_filter Stores all of the filters. + * @global array $wp_filter Stores all of the filters and actions. * @global array $wp_current_filter Stores the list of current filters with the current one last. * * @param string $tag The name of the filter hook. @@ -218,8 +218,8 @@ function apply_filters( $tag, $value ) { * @see apply_filters() This function is identical, but the arguments passed to the * functions hooked to `$tag` are supplied using an array. * - * @global array $wp_filter Stores all of the filters - * @global array $wp_current_filter Stores the list of current filters with the current one last + * @global array $wp_filter Stores all of the filters and actions. + * @global array $wp_current_filter Stores the list of current filters with the current one last. * * @param string $tag The name of the filter hook. * @param array $args The arguments supplied to the functions hooked to $tag. @@ -266,7 +266,7 @@ function apply_filters_ref_array( $tag, $args ) { * * @since 1.2.0 * - * @global array $wp_filter Stores all of the filters + * @global array $wp_filter Stores all of the filters and actions. * * @param string $tag The filter hook to which the function to be removed is hooked. * @param callable $function_to_remove The name of the function which should be removed. @@ -292,7 +292,7 @@ function remove_filter( $tag, $function_to_remove, $priority = 10 ) { * * @since 2.7.0 * - * @global array $wp_filter Stores all of the filters + * @global array $wp_filter Stores all of the filters and actions. * * @param string $tag The filter to remove hooks from. * @param int|bool $priority Optional. The priority number to remove. Default false. @@ -433,9 +433,9 @@ function add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 * @since 5.3.0 Formalized the existing and already documented `...$arg` parameter * by adding it to the function signature. * - * @global array $wp_filter Stores all of the filters + * @global array $wp_filter Stores all of the filters and actions. * @global array $wp_actions Increments the amount of times action was triggered. - * @global array $wp_current_filter Stores the list of current filters with the current one last + * @global array $wp_current_filter Stores the list of current filters with the current one last. * * @param string $tag The name of the action to be executed. * @param mixed ...$arg Optional. Additional arguments which are passed on to the @@ -507,9 +507,9 @@ function did_action( $tag ) { * * @see do_action() This function is identical, but the arguments passed to the * functions hooked to `$tag` are supplied using an array. - * @global array $wp_filter Stores all of the filters + * @global array $wp_filter Stores all of the filters and actions. * @global array $wp_actions Increments the amount of times action was triggered. - * @global array $wp_current_filter Stores the list of current filters with the current one last + * @global array $wp_current_filter Stores the list of current filters with the current one last. * * @param string $tag The name of the action to be executed. * @param array $args The arguments supplied to the functions hooked to `$tag`. @@ -867,7 +867,7 @@ function register_uninstall_hook( $file, $callback ) { * @since 2.5.0 * @access private * - * @global array $wp_filter Stores all of the filters + * @global array $wp_filter Stores all of the filters and actions. * * @param array $args The collected parameters from the hook that was called. */ @@ -897,19 +897,19 @@ function _wp_call_all_hook( $args ) { * @link https://core.trac.wordpress.org/ticket/3875 * * @since 2.2.3 + * @since 5.3.0 Removed workarounds for spl_object_hash(). + * `$tag` and `$priority` are no longer used, + * and the function always returns a string. * @access private * - * @global array $wp_filter Storage for all of the filters and actions. + * @global array $wp_filter Stores all of the filters and actions. * @staticvar int $filter_id_count * - * @param string $tag Used in counting how many hooks were applied - * @param callable $function Used for creating unique id - * @param int|bool $priority Used in counting how many hooks were applied. If === false - * and $function is an object reference, we return the unique - * id only if it already has one, false otherwise. - * @return string|false Unique ID for usage as array key or false if $priority === false - * and $function is an object reference, and it does not already have - * a unique id. + * @param string $tag Unused. The name of the filter to build ID for. + * @param callable $function The function to generate ID for. + * @param int $priority Unused. The order in which the functions associated + * with a particular action are executed. + * @return string Unique ID for usage as array key. */ function _wp_filter_build_unique_id( $tag, $function, $priority ) { global $wp_filter; @@ -920,17 +920,17 @@ function _wp_filter_build_unique_id( $tag, $function, $priority ) { } if ( is_object( $function ) ) { - // Closures are currently implemented as objects + // Closures are currently implemented as objects. $function = array( $function, '' ); } else { $function = (array) $function; } if ( is_object( $function[0] ) ) { - // Object Class Calling + // Object class calling. return spl_object_hash( $function[0] ) . $function[1]; } elseif ( is_string( $function[0] ) ) { - // Static Calling + // Static calling. return $function[0] . '::' . $function[1]; } } diff --git a/tests/phpunit/includes/functions.php b/tests/phpunit/includes/functions.php index f4491b7a77..17e075c701 100644 --- a/tests/phpunit/includes/functions.php +++ b/tests/phpunit/includes/functions.php @@ -38,11 +38,17 @@ function tests_reset__SERVER() { // phpcs:ignore WordPress.NamingConventions.Val /** * Adds hooks before loading WP. * - * @param string $tag The name for the filter to add. - * @param object|array $function_to_add The function/callback to execute on call. - * @param int $priority The priority. - * @param int $accepted_args The amount of accepted arguments. - * @return bool Always true. + * @see add_filter() + * + * @param string $tag The name of the filter to hook the $function_to_add callback to. + * @param callable $function_to_add 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 action 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 action. Default 10. + * @param int $accepted_args Optional. The number of arguments the function accepts. Default 1. + * @return true */ function tests_add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) { global $wp_filter; @@ -50,7 +56,8 @@ function tests_add_filter( $tag, $function_to_add, $priority = 10, $accepted_arg if ( function_exists( 'add_filter' ) ) { add_filter( $tag, $function_to_add, $priority, $accepted_args ); } else { - $idx = _test_filter_build_unique_id( $tag, $function_to_add, $priority ); + $idx = _test_filter_build_unique_id( $tag, $function_to_add, $priority ); + $wp_filter[ $tag ][ $priority ][ $idx ] = array( 'function' => $function_to_add, 'accepted_args' => $accepted_args, @@ -62,10 +69,13 @@ function tests_add_filter( $tag, $function_to_add, $priority = 10, $accepted_arg /** * Generates a unique function ID based on the given arguments. * - * @param string $tag Unused. The name of the filter to build ID for. - * @param object|array $function The function to generate ID for. - * @param int $priority Unused. The priority. - * @return string Unique function ID. + * @see _wp_filter_build_unique_id() + * + * @param string $tag Unused. The name of the filter to build ID for. + * @param callable $function The function to generate ID for. + * @param int $priority Unused. The order in which the functions + * associated with a particular action are executed. + * @return string Unique function ID for usage as array key. */ function _test_filter_build_unique_id( $tag, $function, $priority ) { if ( is_string( $function ) ) { @@ -80,9 +90,10 @@ function _test_filter_build_unique_id( $tag, $function, $priority ) { } if ( is_object( $function[0] ) ) { + // Object class calling. return spl_object_hash( $function[0] ) . $function[1]; } elseif ( is_string( $function[0] ) ) { - // Static Calling. + // Static calling. return $function[0] . $function[1]; } }