From e088de67e899aa0aaf7336b58955adbaad52526c Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Mon, 2 Jan 2023 00:28:02 +0000
Subject: [PATCH] Tests: Update the terminology used for filter names in
 `tests_add_filter()`.

This commit renames the `$tag` and `$function_to_add` parameters to match the `add_filter()` function signature.

Includes:
* Renaming the `$tag` parameter to `$hook_name`.
* Renaming the `$function_to_add` parameter to `$callback`.
* Synchronizing documentation for:
 * `tests_add_filter()` and `add_filter()`
 * `_test_filter_build_unique_id()` and `_wp_filter_build_unique_id()`

Follow-up to [760/tests], [38582], [43555], [46801], [50807], [52300], [53804], [53805], [55023].

See #56793.

git-svn-id: https://develop.svn.wordpress.org/trunk@55025 602fd350-edb4-49c9-b593-d223f7449a82
---
 tests/phpunit/includes/functions.php | 47 ++++++++++++++++------------
 1 file changed, 27 insertions(+), 20 deletions(-)

diff --git a/tests/phpunit/includes/functions.php b/tests/phpunit/includes/functions.php
index 71bedc7893..0c9dbd019f 100644
--- a/tests/phpunit/includes/functions.php
+++ b/tests/phpunit/includes/functions.php
@@ -37,46 +37,53 @@ function tests_reset__SERVER() { // phpcs:ignore WordPress.NamingConventions.Val
 /**
  * Adds hooks before loading WP.
  *
- * @see add_filter()
+ * @since UT (3.7.0)
  *
- * @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
+ * @see add_filter()
+ * @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 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 Always returns true.
  */
-function tests_add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
+function tests_add_filter( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
 	global $wp_filter;
 
 	if ( function_exists( 'add_filter' ) ) {
-		add_filter( $tag, $function_to_add, $priority, $accepted_args );
+		add_filter( $hook_name, $callback, $priority, $accepted_args );
 	} else {
-		$idx = _test_filter_build_unique_id( $tag, $function_to_add, $priority );
+		$idx = _test_filter_build_unique_id( $hook_name, $callback, $priority );
 
-		$wp_filter[ $tag ][ $priority ][ $idx ] = array(
-			'function'      => $function_to_add,
+		$wp_filter[ $hook_name ][ $priority ][ $idx ] = array(
+			'function'      => $callback,
 			'accepted_args' => $accepted_args,
 		);
 	}
+
 	return true;
 }
 
 /**
  * Generates a unique function ID based on the given arguments.
  *
+ * @since UT (3.7.0)
+ *
  * @see _wp_filter_build_unique_id()
  *
- * @param string   $tag      Unused. The name of the filter to build ID for.
- * @param callable $callback The function to generate ID for.
- * @param int      $priority Unused. The order in which the functions
- *                           associated with a particular action are executed.
+ * @param string                $hook_name Unused. The name of the filter to build ID for.
+ * @param callable|string|array $callback  The callback to generate ID for. The callback may
+ *                                         or may not exist.
+ * @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, $callback, $priority ) {
+function _test_filter_build_unique_id( $hook_name, $callback, $priority ) {
 	if ( is_string( $callback ) ) {
 		return $callback;
 	}