From 13f368c865fdb475cec79c0f9d1764b4db360d15 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Wed, 9 Sep 2020 23:47:31 +0200
Subject: [PATCH] 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.
---
 PHPCSUtils/Tokens/Collections.php             | 33 +++++++++++---
 PHPCSUtils/Utils/ControlStructures.php        |  2 +-
 PHPCSUtils/Utils/ObjectDeclarations.php       |  2 +-
 PHPCSUtils/Utils/Operators.php                |  2 +-
 .../Collections/NamespacedNameTokensTest.php  | 43 +++++++++++++++++++
 5 files changed, 73 insertions(+), 9 deletions(-)
 create mode 100644 Tests/Tokens/Collections/NamespacedNameTokensTest.php

diff --git a/PHPCSUtils/Tokens/Collections.php b/PHPCSUtils/Tokens/Collections.php
index f5380726..6d6540f2 100644
--- 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
index 085a1c3f..afe86503 100644
--- 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
index 843e4f10..34aca8ab 100644
--- 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
index 1a8343c0..cc1a446b 100644
--- 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
new file mode 100644
index 00000000..0df1364f
--- /dev/null
+++ 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());
+    }
+}