Collections: deprecate $OONameTokens in favour of namespacedNameTokens()

Deprecate the `$OONameTokens` property in favour of a new `Collections::namespacedNameTokens()` method. PHP 8.0 introduces three new tokens to represent identifier names. As those tokens will not always be available, a property can't handle this. In anticipation of the introduction of the new tokens, I'm deprecating the `Collections::$OONameTokens` property to prevent BC breaks at a later point in time. Includes adding unit tests for the new method. Includes switching out existing uses of the deprecated property for the new method.
PHPCSStandards · Sep 13, 2020 · 13f368c · 13f368c
1 parent 452bf6b
commit 13f368c
Show file tree

Hide file tree

Showing 5 changed files with 73 additions and 9 deletions.
diff --git a/PHPCSUtils/Tokens/Collections.php b/PHPCSUtils/Tokens/Collections.php
@@ -301,15 +301,13 @@ class Collections
     ];
 
     /**
-     * Tokens types which can be encountered in the fully/partially qualified name of an OO structure.
-     *
-     * Example:
-     * ```php
-     * echo namespace\Sub\ClassName::method();
-     * ```
+     * DEPRECATED: Tokens types which can be encountered in the fully/partially qualified name of an OO structure.
      *
      * @since 1.0.0-alpha3
      *
+     * @deprecated 1.0.0-alpha4 Use the {@see \PHPCSUtils\Tokens\Collections::namespacedNameTokens()}
+     *                          method instead.
+     *
      * @var array <int|string> => <int|string>
      */
     public static $OONameTokens = [
@@ -579,6 +577,29 @@ public static function functionDeclarationTokensBC()
         return $tokens;
     }
 
+    /**
+     * Tokens types which can be encountered in a fully, partially or unqualified name.
+     *
+     * Example:
+     * ```php
+     * echo namespace\Sub\ClassName::method();
+     * ```
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @return array <int|string> => <int|string>
+     */
+    public static function namespacedNameTokens()
+    {
+        $tokens = [
+            \T_NS_SEPARATOR => \T_NS_SEPARATOR,
+            \T_NAMESPACE    => \T_NAMESPACE,
+            \T_STRING       => \T_STRING,
+        ];
+
+        return $tokens;
+    }
+
     /**
      * Object operators.
      *

diff --git a/PHPCSUtils/Utils/ControlStructures.php b/PHPCSUtils/Utils/ControlStructures.php
@@ -396,7 +396,7 @@ public static function getCaughtExceptions(File $phpcsFile, $stackPtr)
                 continue;
             }
 
-            if (isset(Collections::$OONameTokens[$tokens[$i]['code']]) === false) {
+            if (isset(Collections::namespacedNameTokens()[$tokens[$i]['code']]) === false) {
                 // Add the current exception to the result array.
                 $exceptions[] = [
                     'type'           => $foundName,

diff --git a/PHPCSUtils/Utils/ObjectDeclarations.php b/PHPCSUtils/Utils/ObjectDeclarations.php
@@ -350,7 +350,7 @@ private static function findNames(File $phpcsFile, $stackPtr, $keyword, $allowed
             return false;
         }
 
-        $find  = Collections::$OONameTokens + Tokens::$emptyTokens;
+        $find  = Collections::namespacedNameTokens() + Tokens::$emptyTokens;
         $names = [];
         $end   = $keywordPtr;
         do {

diff --git a/PHPCSUtils/Utils/Operators.php b/PHPCSUtils/Utils/Operators.php
@@ -151,7 +151,7 @@ public static function isReference(File $phpcsFile, $stackPtr)
                 return true;
             } else {
                 $skip   = Tokens::$emptyTokens;
-                $skip  += Collections::$OONameTokens;
+                $skip  += Collections::namespacedNameTokens();
                 $skip  += Collections::$OOHierarchyKeywords;
                 $skip[] = \T_DOUBLE_COLON;
 

diff --git a/Tests/Tokens/Collections/NamespacedNameTokensTest.php b/Tests/Tokens/Collections/NamespacedNameTokensTest.php
@@ -0,0 +1,43 @@
+<?php
+/**
+ * PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
+ *
+ * @package   PHPCSUtils
+ * @copyright 2019-2020 PHPCSUtils Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSUtils
+ */
+
+namespace PHPCSUtils\Tests\Tokens\Collections;
+
+use PHPCSUtils\Tokens\Collections;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Test class.
+ *
+ * @covers \PHPCSUtils\Tokens\Collections::namespacedNameTokens
+ *
+ * @group collections
+ *
+ * @since 1.0.0
+ */
+class NamespacedNameTokensTest extends TestCase
+{
+
+    /**
+     * Test the method.
+     *
+     * @return void
+     */
+    public function testNamespacedNameTokens()
+    {
+        $expected = [
+            \T_NS_SEPARATOR => \T_NS_SEPARATOR,
+            \T_NAMESPACE    => \T_NAMESPACE,
+            \T_STRING       => \T_STRING,
+        ];
+
+        $this->assertSame($expected, Collections::namespacedNameTokens());
+    }
+}