PHP 8.1 | Utils\PassedParameters: change named param implementation/n…

…amed params after variadic

Follow up on 235 and 361.

As of PHP 8.1, named parameters after argument unpacking in function calls is allowed. This has implications for how to retrieve a parameter from the parameter stack in the `PassedParameters::getParameterFromStack()` method and exposes a pre-existing short-coming in the method as argument unpacking was not taken into account.

While argument unpacking will always throw the retrieval of a specific parameter off if that specific parameter is one of the parameters being unpacked, the method can still be improved to handle this better in the context of named parameters.

To make this more straight-forward, I'm changing the implementation for support for named parameters in the `PassedParameters::getParameters()` method.

Previously (but so far unreleased), the return array for named parameters would contain three extra keys: `name_start`, `name_end` and `name` and the top-level index for the parameter would be based on the position of the parameter in the function call.

As support for PHPCS < 3.7.1 has been dropped, the `name_start` and `name_end` are no longer relevant as the tokenization of the names will be consistent and will always be `T_PARAM_NAME` - `T_COLON`.
(This was previously not the case as prior to PHPCS 3.6.0, the tokenization of parameter labels could vary based on the label and the spacing used).
The `name_start` and `name_end` keys are now being replaced by a `name_token` key pointing to the `T_PARAM_NAME` token.

On top of that, for named parameters, the position in the function call is irrelevant, so having the position as the top-level index is redundant.

So... this commit makes the following changes:
1. `PassedParameters::getParameters()`: the `name_start` and `name_end` keys have been removed and instead a `name_token` key will be added.
    Note: the `name` key in the parameter sub-array _will_ also still be set as both the `PassedParameters::getParameter()` method as well as the `PassedParameters::getParameterFromStack()` method will return only the parameter specific sub-array and what with a sniff potentially passing multiple parameter names, it is still useful to know which one was matched.
2. `PassedParameters::getParameters()`: the _key_ for the parameter will now be either its position or the parameter name.
    This does mean that the behaviour for function calls passing _duplicate_ named parameters has changed. The first parameter using the name will be in the top-level array by name, the second parameter using the same name, will be in the array using their position as the key (as the duplicate name would otherwise overwrite the first entry).
    As duplicate parameter names being used in a function call would result in an `Error` exception in PHP anyway, I'm not too concerned about this.
3. `PassedParameters::getParameterFromStack()` will now attempt to find a named parameter first and only look for the positional variant after.

Includes:
* An additional test for the `PassedParameters::getParameterFromStack()` method to verify that retrieving a named parameter after a variadic parameter is handled correctly.
* An additional test for the `PassedParameters::getParameterCount()` method to safeguard that duplicate parameter names will still result in a correct parameter count.
* Updating the test expectations in various test classes.
* A minor ruleset tweak to exempt the `GetParametersNamedTest` class from the `Universal.Arrays.MixedArrayKeyTypes` sniff as the return value of `PassedParameters::getParameters()` may now contain mixed array keys.
* Removing an unused `use` statement (follow up after 369).

Note: it will still be the responsibility of individual sniffs to take argument unpacking in function calls into account when examining parameters.

Refs:
* https://www.php.net/manual/en/migration81.new-features.php#migration81.new-features.core.named-arg-after-unpack

PHPCSUtils/Utils/PassedParameters.php

@@ -17,7 +17,6 @@
 use PHPCSUtils\Tokens\Collections;
 use PHPCSUtils\Utils\Arrays;
 use PHPCSUtils\Utils\GetTokensAsString;
-use PHPCSUtils\Utils\NamingConventions;
 
 /**
  * Utility functions to retrieve information about parameters passed to function calls,
@@ -157,8 +156,9 @@ public static function hasParameters(File $phpcsFile, $stackPtr, $isShortArray =
      * See {@see PassedParameters::hasParameters()} for information on the supported constructs.
      *
      * @since 1.0.0
-     * @since 1.0.0-alpha4 Added support for PHP 8.0 function calls with named arguments by
-     *                     introducing the new `'name_start'`, `'name_end'` and `'name'` index keys.
+     * @since 1.0.0-alpha4 Added support for PHP 8.0 function calls with named arguments by introducing
+     *                     the `'name'` and `'name_token'` index keys as well as using the name
+     *                     as the index for the top-level array for named parameters.
      *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile    The file where this token was found.
      * @param int                         $stackPtr     The position of function call name,
@@ -170,32 +170,28 @@ public static function hasParameters(File $phpcsFile, $stackPtr, $isShortArray =
      *                                                  Efficiency tweak for when this has already been established,
      *                                                  Use with EXTREME care.
      *
-     * @return array A multi-dimentional array information on each parameter/array item.
+     * @return array A multi-dimentional array with information on each parameter/array item.
      *               The information gathered about each parameter/array item is in the following format:
      *               ```php
-     *               1 => array(
+     *               [1] => array(
      *                 'start' => int,    // The stack pointer to the first token in the parameter/array item.
      *                 'end'   => int,    // The stack pointer to the last token in the parameter/array item.
      *                 'raw'   => string, // A string with the contents of all tokens between `start` and `end`.
      *                 'clean' => string, // Same as `raw`, but all comment tokens have been stripped out.
      *               )
      *               ```
-     *               For function calls passing named arguments, the format is as follows:
+     *               If a named parameter is encountered in a function call, the top-level index will not be
+     *               the parameter _position_, but the _parameter name_ and the array will include two extra keys:
      *               ```php
-     *               1 => array(
-     *                 'name_start' => int,    // The stack pointer to the first token in the parameter name.
-     *                 'name_end'   => int,    // The stack pointer to the last token in the parameter name.
-     *                                         // This will point to the colon.
-     *                 'name'       => string, // The parameter name as a string (without the colon).
-     *                 'start'      => int,    // The stack pointer to the first token in the parameter value.
-     *                 'end'        => int,    // The stack pointer to the last token in the parameter value.
-     *                 'raw'        => string, // A string with the contents of all tokens between `start` and `end`.
-     *                 'clean'      => string, // Same as `raw`, but all comment tokens have been stripped out.
+     *               [parameter_name] => array(
+     *                 'name'       => string, // The parameter name (without the colon).
+     *                 'name_token' => int,    // The stack pointer to the parameter name token.
      *               )
      *               ```
      *               The `'start'`, `'end'`, `'raw'` and `'clean'` indexes will always contain just and only
      *               information on the parameter value.
-     *               _Note: The array starts at index 1._
+     *               _Note: The array starts at index 1 for positional parameters._
+     *                     _The key for named parameters will be the parameter name._
      *               If no parameters/array items are found, an empty array will be returned.
      *
      * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the token passed is not one of the
@@ -288,6 +284,7 @@ public static function getParameters(File $phpcsFile, $stackPtr, $limit = 0, $is
 
             // Ok, we've reached the end of the parameter.
             $paramEnd = ($nextComma - 1);
+            $key      = $cnt;
 
             if ($mayHaveNames === true) {
                 $firstNonEmpty = $phpcsFile->findNext(Tokens::$emptyTokens, $paramStart, ($paramEnd + 1), true);
@@ -302,18 +299,22 @@ public static function getParameters(File $phpcsFile, $stackPtr, $limit = 0, $is
                     if ($tokens[$secondNonEmpty]['code'] === \T_COLON
                         && $tokens[$firstNonEmpty]['code'] === \T_PARAM_NAME
                     ) {
-                        $parameters[$cnt]['name_start'] = $paramStart;
-                        $parameters[$cnt]['name_end']   = $secondNonEmpty;
-                        $parameters[$cnt]['name']       = $tokens[$firstNonEmpty]['content'];
+                        if (isset($parameters[$tokens[$firstNonEmpty]['content']]) === false) {
+                            // Set the key to be the name, but only if we've not seen this name before.
+                            $key = $tokens[$firstNonEmpty]['content'];
+                        }
+
+                        $parameters[$key]['name']       = $tokens[$firstNonEmpty]['content'];
+                        $parameters[$key]['name_token'] = $firstNonEmpty;
                         $paramStart                     = ($secondNonEmpty + 1);
                     }
                 }
             }
 
-            $parameters[$cnt]['start'] = $paramStart;
-            $parameters[$cnt]['end']   = $paramEnd;
-            $parameters[$cnt]['raw']   = \trim(GetTokensAsString::normal($phpcsFile, $paramStart, $paramEnd));
-            $parameters[$cnt]['clean'] = \trim(GetTokensAsString::noComments($phpcsFile, $paramStart, $paramEnd));
+            $parameters[$key]['start'] = $paramStart;
+            $parameters[$key]['end']   = $paramEnd;
+            $parameters[$key]['raw']   = \trim(GetTokensAsString::normal($phpcsFile, $paramStart, $paramEnd));
+            $parameters[$key]['clean'] = \trim(GetTokensAsString::noComments($phpcsFile, $paramStart, $paramEnd));
 
             // Check if there are more tokens before the closing parenthesis.
             // Prevents function calls with trailing comma's from setting an extra parameter:
@@ -476,7 +477,18 @@ public static function getParameterFromStack(array $parameters, $paramOffset, $p
             return false;
         }
 
-        // First check for positional parameters.
+        // First check for a named parameter.
+        if (empty($paramNames) === false) {
+            $paramNames = (array) $paramNames;
+            foreach ($paramNames as $name) {
+                // Note: parameter names are case-sensitive!.
+                if (isset($parameters[$name]) === true) {
+                    return $parameters[$name];
+                }
+            }
+        }
+
+        // Next check for positional parameters.
         if (isset($parameters[$paramOffset]) === true
             && isset($parameters[$paramOffset]['name']) === false
         ) {
@@ -489,19 +501,6 @@ public static function getParameterFromStack(array $parameters, $paramOffset, $p
             );
         }
 
-        $paramNames = \array_flip((array) $paramNames);
-
-        // Next check if a named parameter was passed with the specified name.
-        foreach ($parameters as $paramDetails) {
-            if (isset($paramDetails['name']) === false) {
-                continue;
-            }
-
-            if (isset($paramNames[$paramDetails['name']]) === true) {
-                return $paramDetails;
-            }
-        }
-
         return false;
     }
 }

Tests/Utils/PassedParameters/GetParameterCountTest.inc

@@ -162,6 +162,10 @@ Partially\Qualified\myfunction( $a );
 /* testFunctionCallNamespaceOperator */
 namespace\myfunction( $a );
 
+/* testFunctionCallNamedParamsDuplicateName */
+// Error Exception, but not the concern of PHPCSUtils. Should still be handled.
+test(param: 1, param: 2);
+
 /* testLongArray1 */
 $foo = array( 1, 2, 3, 4, 5, 6, true );
 

Tests/Utils/PassedParameters/GetParameterCountTest.php

@@ -277,6 +277,10 @@ public function dataGetParameterCount()
                 'expected'      => 1,
                 'targetContent' => ($php8Names === true) ? null : 'myfunction',
             ],
+            'function-call-named-params-duplicate-name' => [
+                'testMarker'    => '/* testFunctionCallNamedParamsDuplicateName */',
+                'expected'      => 2,
+            ],
 
             // Long arrays.
             'long-array-1' => [

Tests/Utils/PassedParameters/GetParameterFromStackTest.inc

@@ -57,3 +57,7 @@ setcookie(
     'name',
     expires: time() + (60 * 60 * 24),
 );
+
+/* testPHP81NamedParamAfterVariadic */
+// Prior to PHP 8.1, this was a compile error, but this is now supported.
+test($positional, ...$variadic, namedA: $valueA, namedB: $valueB);