Tokenizer: T_USE tokens for closure use now contain parenthesis information

gsherwood · jrfnl · jrfnl · commit de8442a0f516 · 2025-04-17T15:59:47.000+02:00
Closure `use` keywords will now be recognized as `parenthesis_owner`s and both the keyword, as well as the associated parenthesis will receive the `parenthesis_owner`, `parenthesis_opener` and `parenthesis_closer` indexes.

Includes:
* A tweak in the PHP tokenizer to handle return type recognition in combination with closures with `use` correctly.
    This tweaks is covered by pre-existing tests.
* A dedicated set of tests for the handling of `T_USE` tokens in this context to safeguard that `use` keywords for import use statements and trait use statements do not get the `parenthesis_*` indexes.
    Tests taken from PR squizlabs/PHP_CodeSniffer 3104 and updated to have named data sets and failure messages for all assertions.
* With this change in place, the tests for the `File::getMethodParameters()` method will start failing straight away, so this commit _also_ includes a fix to that method to allow for this change, while maintaining the pre-existing behaviour.
    Includes some additional tests to document the method behaviour regarding closure `use` during live coding.
* With this change in place, the tests for the `Squiz/MemberVarScope` sniff would also start to fail.
    This is fixed by the change in the `AbstractVariableSniff` class to allow for `T_USE` now being a parenthesis owner.

Fixes squizlabs/PHP_CodeSniffer 2593
Replaces squizlabs/PHP_CodeSniffer 3104 (made redundant by the previous PR)

Co-authored-by: jrfnl &lt;jrfnl@users.noreply.github.com&gt;
diff --git a/src/Files/File.php b/src/Files/File.php
@@ -1313,20 +1313,19 @@ public function getMethodParameters($stackPtr)
             throw new RuntimeException('$stackPtr must be of type T_FUNCTION or T_CLOSURE or T_USE or T_FN');
         }
 
-        if ($this->tokens[$stackPtr]['code'] === T_USE) {
-            $opener = $this->findNext(T_OPEN_PARENTHESIS, ($stackPtr + 1));
-            if ($opener === false || isset($this->tokens[$opener]['parenthesis_owner']) === true) {
-                throw new RuntimeException('$stackPtr was not a valid T_USE');
-            }
-        } else {
-            if (isset($this->tokens[$stackPtr]['parenthesis_opener']) === false) {
-                // Live coding or syntax error, so no params to find.
-                return [];
-            }
+        if ($this->tokens[$stackPtr]['code'] === T_USE
+            && isset($this->tokens[$stackPtr]['parenthesis_owner']) === false
+        ) {
+            throw new RuntimeException('$stackPtr was not a valid T_USE');
+        }
 
-            $opener = $this->tokens[$stackPtr]['parenthesis_opener'];
+        if (isset($this->tokens[$stackPtr]['parenthesis_opener']) === false) {
+            // Live coding or syntax error, so no params to find.
+            return [];
         }
 
+        $opener = $this->tokens[$stackPtr]['parenthesis_opener'];
+
         if (isset($this->tokens[$opener]['parenthesis_closer']) === false) {
             // Live coding or syntax error, so no params to find.
             return [];
diff --git a/src/Sniffs/AbstractVariableSniff.php b/src/Sniffs/AbstractVariableSniff.php
@@ -118,19 +118,13 @@ final protected function processTokenWithinScope(File $phpcsFile, $stackPtr, $cu
         if ($inFunction === false && isset($tokens[$stackPtr]['nested_parenthesis']) === true) {
             foreach ($tokens[$stackPtr]['nested_parenthesis'] as $opener => $closer) {
                 if (isset($tokens[$opener]['parenthesis_owner']) === false) {
-                    // Check if this is a USE statement for a closure.
-                    $prev = $phpcsFile->findPrevious(Tokens::$emptyTokens, ($opener - 1), null, true);
-                    if ($tokens[$prev]['code'] === T_USE) {
-                        $inFunction = true;
-                        break;
-                    }
-
                     continue;
                 }
 
                 $owner = $tokens[$opener]['parenthesis_owner'];
                 if ($tokens[$owner]['code'] === T_FUNCTION
                     || $tokens[$owner]['code'] === T_CLOSURE
+                    || $tokens[$owner]['code'] === T_USE
                 ) {
                     $inFunction = true;
                     break;
diff --git a/src/Tokenizers/PHP.php b/src/Tokenizers/PHP.php
@@ -3207,6 +3207,7 @@ protected function processAdditional()
                             if ($this->tokens[$this->tokens[$y]['parenthesis_owner']]['code'] === T_FUNCTION
                                 || $this->tokens[$this->tokens[$y]['parenthesis_owner']]['code'] === T_CLOSURE
                                 || $this->tokens[$this->tokens[$y]['parenthesis_owner']]['code'] === T_FN
+                                || $this->tokens[$this->tokens[$y]['parenthesis_owner']]['code'] === T_USE
                             ) {
                                 $confirmed = true;
                             }
@@ -3215,15 +3216,14 @@ protected function processAdditional()
                         }
 
                         // Arrow functions may not have the parenthesis_owner set correctly yet.
-                        // Closure use tokens won't be parentheses owners until PHPCS 4.0.
                         if (isset($this->tokens[$y]['parenthesis_opener']) === true) {
                             for ($z = ($this->tokens[$y]['parenthesis_opener'] - 1); $z > 0; $z--) {
                                 if (isset(Tokens::$emptyTokens[$this->tokens[$z]['code']]) === false) {
                                     break;
                                 }
                             }
 
-                            if ($this->tokens[$z]['code'] === T_FN || $this->tokens[$z]['code'] === T_USE) {
+                            if ($this->tokens[$z]['code'] === T_FN) {
                                 $confirmed = true;
                             }
                         }
diff --git a/src/Util/Tokens.php b/src/Util/Tokens.php
@@ -358,6 +358,7 @@ final class Tokens
         T_LIST       => T_LIST,
         T_FUNCTION   => T_FUNCTION,
         T_CLOSURE    => T_CLOSURE,
+        T_USE        => T_USE,
         T_ANON_CLASS => T_ANON_CLASS,
         T_WHILE      => T_WHILE,
         T_FOR        => T_FOR,
diff --git a/tests/Core/File/GetMethodParametersParseError3Test.inc b/tests/Core/File/GetMethodParametersParseError3Test.inc
@@ -0,0 +1,5 @@
+<?php
+
+// Intentional parse error. Missing closure use parentheses. This should be the only test in the file.
+/* testParseError */
+$cl = function ($a) use
diff --git a/tests/Core/File/GetMethodParametersParseError3Test.php b/tests/Core/File/GetMethodParametersParseError3Test.php
@@ -0,0 +1,37 @@
+<?php
+/**
+ * Tests for the \PHP_CodeSniffer\Files\File::getMethodParameters method.
+ *
+ * @copyright 2025 PHPCSStandards Contributors
+ * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Tests\Core\File;
+
+use PHP_CodeSniffer\Tests\Core\AbstractMethodTestCase;
+
+/**
+ * Tests for the \PHP_CodeSniffer\Files\File::getMethodParameters method.
+ *
+ * @covers \PHP_CodeSniffer\Files\File::getMethodParameters
+ */
+final class GetMethodParametersParseError3Test extends AbstractMethodTestCase
+{
+
+
+    /**
+     * Test receiving an empty array when encountering a specific parse error.
+     *
+     * @return void
+     */
+    public function testParseError()
+    {
+        $this->expectRunTimeException('$stackPtr was not a valid T_USE');
+
+        $target = $this->getTargetToken('/* testParseError */', [T_USE]);
+        self::$phpcsFile->getMethodParameters($target);
+
+    }//end testParseError()
+
+
+}//end class
diff --git a/tests/Core/File/GetMethodParametersParseError4Test.inc b/tests/Core/File/GetMethodParametersParseError4Test.inc
@@ -0,0 +1,5 @@
+<?php
+
+// Intentional parse error. Missing closure use close parenthesis. This should be the only test in the file.
+/* testParseError */
+$cl = function ($a) use (
diff --git a/tests/Core/File/GetMethodParametersParseError4Test.php b/tests/Core/File/GetMethodParametersParseError4Test.php
@@ -0,0 +1,37 @@
+<?php
+/**
+ * Tests for the \PHP_CodeSniffer\Files\File::getMethodParameters method.
+ *
+ * @copyright 2025 PHPCSStandards Contributors
+ * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Tests\Core\File;
+
+use PHP_CodeSniffer\Tests\Core\AbstractMethodTestCase;
+
+/**
+ * Tests for the \PHP_CodeSniffer\Files\File::getMethodParameters method.
+ *
+ * @covers \PHP_CodeSniffer\Files\File::getMethodParameters
+ */
+final class GetMethodParametersParseError4Test extends AbstractMethodTestCase
+{
+
+
+    /**
+     * Test receiving an empty array when encountering a specific parse error.
+     *
+     * @return void
+     */
+    public function testParseError()
+    {
+        $target = $this->getTargetToken('/* testParseError */', [T_USE]);
+        $result = self::$phpcsFile->getMethodParameters($target);
+
+        $this->assertSame([], $result);
+
+    }//end testParseError()
+
+
+}//end class
diff --git a/tests/Core/Tokenizers/Tokenizer/CreateTokenMapClosureUseParenthesesParseErrorTest.inc b/tests/Core/Tokenizers/Tokenizer/CreateTokenMapClosureUseParenthesesParseErrorTest.inc
@@ -0,0 +1,5 @@
+<?php
+
+// Intentional parse error. Live coding. This has to be the only test in the file without a new line after it.
+/* testLiveCoding */
+use
diff --git a/tests/Core/Tokenizers/Tokenizer/CreateTokenMapClosureUseParenthesesParseErrorTest.php b/tests/Core/Tokenizers/Tokenizer/CreateTokenMapClosureUseParenthesesParseErrorTest.php
@@ -0,0 +1,40 @@
+<?php
+/**
+ * Tests the adding of the "parenthesis" keys to closure use tokens.
+ *
+ * @copyright 2020 PHPCSStandards and contributors
+ * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Tests\Core\Tokenizers\Tokenizer;
+
+use PHP_CodeSniffer\Tests\Core\Tokenizers\AbstractTokenizerTestCase;
+
+/**
+ * Tests the adding of the "parenthesis" keys to closure use tokens.
+ *
+ * @covers PHP_CodeSniffer\Tokenizers\Tokenizer::createTokenMap
+ */
+final class CreateTokenMapClosureUseParenthesesParseErrorTest extends AbstractTokenizerTestCase
+{
+
+
+    /**
+     * Test (and document) the behaviour of the parentheses setting during live coding, when a
+     * `use` token is encountered at the very end of a file.
+     *
+     * @return void
+     */
+    public function testLiveCoding()
+    {
+        $tokens = $this->phpcsFile->getTokens();
+        $use    = $this->getTargetToken('/* testLiveCoding */', T_USE);
+
+        $this->assertArrayNotHasKey('parenthesis_owner', $tokens[$use], 'parenthesis_owner key is set');
+        $this->assertArrayNotHasKey('parenthesis_opener', $tokens[$use], 'parenthesis_opener key is set');
+        $this->assertArrayNotHasKey('parenthesis_closer', $tokens[$use], 'parenthesis_closer key is set');
+
+    }//end testLiveCoding()
+
+
+}//end class
diff --git a/tests/Core/Tokenizers/Tokenizer/CreateTokenMapClosureUseParenthesesTest.inc b/tests/Core/Tokenizers/Tokenizer/CreateTokenMapClosureUseParenthesesTest.inc
@@ -0,0 +1,32 @@
+<?php
+
+/* testUseImportSimple */
+use Imported\ClassName;
+
+$a = (1 + 2);
+
+/* testUseImportGroup */
+use Imported\Package\{
+    Classname,
+};
+
+$a = (1 + 2);
+
+$closure = function($param) /* testClosureUse */ use ($var) {};
+
+class ClassUsingTrait {
+    /* testUseTrait */
+    use MyTopLevelTrait { oldfunction as Foo; }
+
+    public function functionName() {
+        $closure = function($param) /* testClosureUseNestedInClass */ use ($var) {} ?>
+        <?php
+
+        $anon_class = new class($param) {
+            /* testUseTraitInNestedAnonClass */
+            use MyNestedTrait { oldfunction as Foo; }
+        };
+
+        return $anon_class('foo');
+    }
+}
diff --git a/tests/Core/Tokenizers/Tokenizer/CreateTokenMapClosureUseParenthesesTest.php b/tests/Core/Tokenizers/Tokenizer/CreateTokenMapClosureUseParenthesesTest.php
diff --git a/tests/Core/Tokenizers/Tokenizer/CreateTokenMapParenthesesTest.inc b/tests/Core/Tokenizers/Tokenizer/CreateTokenMapParenthesesTest.inc
diff --git a/tests/Core/Tokenizers/Tokenizer/CreateTokenMapParenthesesTest.php b/tests/Core/Tokenizers/Tokenizer/CreateTokenMapParenthesesTest.php

Original file line number	Diff line number	Diff line change
`@@ -3207,6 +3207,7 @@ protected function processAdditional()`
`3207`	`3207`	`if ($this->tokens[$this->tokens[$y]['parenthesis_owner']]['code'] === T_FUNCTION`
`3208`	`3208`	`\|\| $this->tokens[$this->tokens[$y]['parenthesis_owner']]['code'] === T_CLOSURE`
`3209`	`3209`	`\|\| $this->tokens[$this->tokens[$y]['parenthesis_owner']]['code'] === T_FN`
	`3210`	`+ \|\| $this->tokens[$this->tokens[$y]['parenthesis_owner']]['code'] === T_USE`
`3210`	`3211`	`) {`
`3211`	`3212`	`$confirmed = true;`
`3212`	`3213`	`}`
`@@ -3215,15 +3216,14 @@ protected function processAdditional()`
`3215`	`3216`	`}`
`3216`	`3217`
`3217`	`3218`	`// Arrow functions may not have the parenthesis_owner set correctly yet.`
`3218`		`- // Closure use tokens won't be parentheses owners until PHPCS 4.0.`
`3219`	`3219`	`if (isset($this->tokens[$y]['parenthesis_opener']) === true) {`
`3220`	`3220`	`for ($z = ($this->tokens[$y]['parenthesis_opener'] - 1); $z > 0; $z--) {`
`3221`	`3221`	`if (isset(Tokens::$emptyTokens[$this->tokens[$z]['code']]) === false) {`
`3222`	`3222`	`break;`
`3223`	`3223`	`}`
`3224`	`3224`	`}`
`3225`	`3225`
`3226`		`- if ($this->tokens[$z]['code'] === T_FN \|\| $this->tokens[$z]['code'] === T_USE) {`
	`3226`	`+ if ($this->tokens[$z]['code'] === T_FN) {`
`3227`	`3227`	`$confirmed = true;`
`3228`	`3228`	`}`
`3229`	`3229`	`}`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +<?php
++
 +// Intentional parse error. Live coding. This has to be the only test in the file without a new line after it.
 +/* testLiveCoding */
 +use