From 55369a5ef49ce61f8ac67639276c92f29654948f Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Wed, 18 Mar 2020 06:25:43 +0100
Subject: [PATCH 1/4] Collections: compatibility with PHPCS 4.x

** BREAKING CHANGE **

This adds three new methods to the `PHPCSUtils\Tokens\Collections` class:
* `parameterTypeTokensBC()`
* `propertyTypeTokensBC()`
* `returnTypeTokensBC()`

... and adjusts the existing `$parameterTypeTokens`, `$propertyTypeTokens` and `$returnTypeTokens` properties to no longer contain token constants which will be removed in PHPCS 4.x.

As things stands at this time, standards implementing PHPCSUtils which only support PHPCS 3.5.4 or higher, can safely use the properties.

If an external standard wants to continue support for PHPCS < 3.5.4 (return types) or PHPCS < 3.3.0 (parameter and property types), the standard should use the methods instead.

Includes dedicated unit tests for the new methods.

Refs:
* https://github.com/squizlabs/PHP_CodeSniffer/commit/cba0001d0cfdb2349b29655d42ba27f1fba315c6
---
 PHPCSUtils/Tokens/Collections.php             | 150 +++++++++++++++++-
 .../Collections/ParameterTypeTokensBCTest.php |  45 ++++++
 .../Collections/PropertyTypeTokensBCTest.php  |  45 ++++++
 .../Collections/ReturnTypeTokensBCTest.php    |  50 ++++++
 4 files changed, 285 insertions(+), 5 deletions(-)
 create mode 100644 Tests/Tokens/Collections/ParameterTypeTokensBCTest.php
 create mode 100644 Tests/Tokens/Collections/PropertyTypeTokensBCTest.php
 create mode 100644 Tests/Tokens/Collections/ReturnTypeTokensBCTest.php

diff --git a/PHPCSUtils/Tokens/Collections.php b/PHPCSUtils/Tokens/Collections.php
index f78698ac..06d11636 100644
--- a/PHPCSUtils/Tokens/Collections.php
+++ b/PHPCSUtils/Tokens/Collections.php
@@ -10,6 +10,8 @@
 
 namespace PHPCSUtils\Tokens;
 
+use PHPCSUtils\BackCompat\Helper;
+
 /**
  * Collections of related tokens as often used and needed for sniffs.
  *
@@ -276,12 +278,23 @@ class Collections
     /**
      * Token types which can be encountered in a parameter type declaration.
      *
+     * Sister-property to the `Collections::parameterTypeTokensBC()` method.
+     * The property supports PHPCS 3.3.0 and up.
+     * The method supports PHPCS 2.6.0 and up.
+     *
+     * Notable difference:
+     * - The method will include the `T_ARRAY_HINT` token when used with PHPCS 2.x and 3.x.
+     *   This token constant will no longer exist in PHPCS 4.x.
+     *
+     * It is recommended to use the method instead of the property if a standard supports PHPCS < 3.3.0.
+     *
+     * @see \PHPCSUtils\Tokens\Collections::parameterTypeTokensBC() Related method (cross-version).
+
      * @since 1.0.0
      *
      * @var array <int|string> => <int|string>
      */
     public static $parameterTypeTokens = [
-        \T_ARRAY_HINT   => \T_ARRAY_HINT, // PHPCS < 3.3.0.
         \T_CALLABLE     => \T_CALLABLE,
         \T_SELF         => \T_SELF,
         \T_PARENT       => \T_PARENT,
@@ -307,12 +320,23 @@ class Collections
     /**
      * Token types which can be encountered in a property type declaration.
      *
+     * Sister-property to the `Collections::propertyTypeTokensBC()` method.
+     * The property supports PHPCS 3.3.0 and up.
+     * The method supports PHPCS 2.6.0 and up.
+     *
+     * Notable difference:
+     * - The method will include the `T_ARRAY_HINT` token when used with PHPCS 2.x and 3.x.
+     *   This token constant will no longer exist in PHPCS 4.x.
+     *
+     * It is recommended to use the method instead of the property if a standard supports PHPCS < 3.3.0.
+     *
+     * @see \PHPCSUtils\Tokens\Collections::propertyTypeTokensBC() Related method (cross-version).
+     *
      * @since 1.0.0
      *
      * @var array <int|string> => <int|string>
      */
     public static $propertyTypeTokens = [
-        \T_ARRAY_HINT   => \T_ARRAY_HINT, // PHPCS < 3.3.0.
         \T_CALLABLE     => \T_CALLABLE,
         \T_SELF         => \T_SELF,
         \T_PARENT       => \T_PARENT,
@@ -323,6 +347,19 @@ class Collections
     /**
      * Token types which can be encountered in a return type declaration.
      *
+     * Sister-property to the `Collections::returnTypeTokensBC()` method.
+     * The property supports PHPCS 3.5.4 and up.
+     * The method supports PHPCS 2.6.0 and up.
+     *
+     * Notable differences:
+     * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE tokens when used with PHPCS 2.x and 3.x.
+     *   These token constants will no longer exist in PHPCS 4.x.
+     * - The method will include the `T_ARRAY` token which is needed for select arrow functions in PHPCS < 3.5.4.
+     *
+     * It is recommended to use the method instead of the property if a standard supports PHPCS < 3.5.4.
+     *
+     * @see \PHPCSUtils\Tokens\Collections::returnTypeTokensBC() Related method (cross-version).
+     *
      * @since 1.0.0
      *
      * @var array <int|string> => <int|string>
@@ -333,9 +370,6 @@ class Collections
         \T_SELF         => \T_SELF,
         \T_PARENT       => \T_PARENT,
         \T_NS_SEPARATOR => \T_NS_SEPARATOR,
-        \T_RETURN_TYPE  => \T_RETURN_TYPE, // PHPCS 2.4.0 < 3.3.0.
-        \T_ARRAY_HINT   => \T_ARRAY_HINT, // PHPCS < 2.8.0 / PHPCS < 3.5.3 for arrow functions.
-        \T_ARRAY        => \T_ARRAY, // PHPCS < 3.5.4 for select arrow functions.
     ];
 
     /**
@@ -442,4 +476,110 @@ public static function arrowFunctionTokensBC()
 
         return $tokens;
     }
+
+    /**
+     * Token types which can be encountered in a parameter type declaration (cross-version).
+     *
+     * Sister-method to the `$parameterTypeTokens` property.
+     * The property supports PHPCS 3.3.0 and up.
+     * The method supports PHPCS 2.6.0 and up.
+     *
+     * Notable difference:
+     * The method will include the `T_ARRAY_HINT` token when used with PHPCS 2.x and 3.x.
+     * This token constant will no longer exist in PHPCS 4.x.
+     *
+     * It is recommended to use the method instead of the property if a standard supports PHPCS < 3.3.0.
+     *
+     * @see \PHPCSUtils\Tokens\Collections::$parameterTypeTokens Related property (PHPCS 3.3.0+).
+     *
+     * @since 1.0.0
+     *
+     * @return array <int|string> => <int|string>
+     */
+    public static function parameterTypeTokensBC()
+    {
+        $tokens = self::$parameterTypeTokens;
+
+        // PHPCS < 4.0; Needed for support of PHPCS < 3.3.0. For PHPCS 3.3.0+ the constant is no longer used.
+        if (\defined('T_ARRAY_HINT') === true) {
+            $tokens[\T_ARRAY_HINT] = \T_ARRAY_HINT;
+        }
+
+        return $tokens;
+    }
+
+    /**
+     * Token types which can be encountered in a property type declaration (cross-version).
+     *
+     * Sister-method to the `$propertyTypeTokens` property.
+     * The property supports PHPCS 3.3.0 and up.
+     * The method supports PHPCS 2.6.0 and up.
+     *
+     * Notable difference:
+     * The method will include the `T_ARRAY_HINT` token when used with PHPCS 2.x and 3.x.
+     * This token constant will no longer exist in PHPCS 4.x.
+     *
+     * It is recommended to use the method instead of the property if a standard supports PHPCS < 3.3.0.
+     *
+     * @see \PHPCSUtils\Tokens\Collections::$propertyTypeTokens Related property (PHPCS 3.3.0+).
+     *
+     * @since 1.0.0
+     *
+     * @return array <int|string> => <int|string>
+     */
+    public static function propertyTypeTokensBC()
+    {
+        return self::parameterTypeTokensBC();
+    }
+
+    /**
+     * Token types which can be encountered in a return type declaration (cross-version).
+     *
+     * Sister-property to the `Collections::returnTypeTokensBC()` method.
+     * The property supports PHPCS 3.5.4 and up.
+     * The method supports PHPCS 2.6.0 and up.
+     *
+     * Notable differences:
+     * - The method will include the `T_ARRAY_HINT` and the `T_RETURN_TYPE tokens when used with PHPCS 2.x and 3.x.
+     *   These token constants will no longer exist in PHPCS 4.x.
+     * - The method will include the `T_ARRAY` token which is needed for select arrow functions in PHPCS < 3.5.4.
+     *
+     * It is recommended to use the method instead of the property if a standard supports PHPCS < 3.5.4.
+     *
+     * @see \PHPCSUtils\Tokens\Collections::$returnTypeTokens Related property (PHPCS 3.5.4+).
+     *
+     * @since 1.0.0
+     *
+     * @return array <int|string> => <int|string>
+     */
+    public static function returnTypeTokensBC()
+    {
+        $tokens = self::$returnTypeTokens;
+
+        /*
+         * PHPCS < 4.0. Needed for support of PHPCS 2.4.0 < 3.3.0.
+         * For PHPCS 3.3.0+ the constant is no longer used.
+         */
+        if (\defined('T_RETURN_TYPE') === true) {
+            $tokens[\T_RETURN_TYPE] = \T_RETURN_TYPE;
+        }
+
+        /*
+         * PHPCS < 4.0. Needed for support of PHPCS < 2.8.0 / PHPCS < 3.5.3 for arrow functions.
+         * For PHPCS 3.5.3+ the constant is no longer used.
+         */
+        if (\defined('T_ARRAY_HINT') === true) {
+            $tokens[\T_ARRAY_HINT] = \T_ARRAY_HINT;
+        }
+
+        /*
+         * PHPCS < 3.5.4. Needed for support of PHPCS < 3.5.4 for select arrow functions.
+         * For PHPCS 3.5.4+ the constant is no longer used in return type tokenization.
+         */
+        if (\version_compare(Helper::getVersion(), '3.5.4', '<')) {
+            $tokens[\T_ARRAY] = \T_ARRAY;
+        }
+
+        return $tokens;
+    }
 }
diff --git a/Tests/Tokens/Collections/ParameterTypeTokensBCTest.php b/Tests/Tokens/Collections/ParameterTypeTokensBCTest.php
new file mode 100644
index 00000000..0fcb7cf1
--- /dev/null
+++ b/Tests/Tokens/Collections/ParameterTypeTokensBCTest.php
@@ -0,0 +1,45 @@
+<?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\BackCompat\Helper;
+use PHPCSUtils\Tokens\Collections;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Test class.
+ *
+ * @covers \PHPCSUtils\Tokens\Collections::parameterTypeTokensBC
+ *
+ * @group collections
+ *
+ * @since 1.0.0
+ */
+class ParameterTypeTokensBCTest extends TestCase
+{
+
+    /**
+     * Test the method.
+     *
+     * @return void
+     */
+    public function testParameterTypeTokensBC()
+    {
+        $version  = Helper::getVersion();
+        $expected = Collections::$parameterTypeTokens;
+
+        if (\version_compare($version, '3.99.99', '<=') === true) {
+            $expected[\T_ARRAY_HINT] = \T_ARRAY_HINT;
+        }
+
+        $this->assertSame($expected, Collections::parameterTypeTokensBC());
+    }
+}
diff --git a/Tests/Tokens/Collections/PropertyTypeTokensBCTest.php b/Tests/Tokens/Collections/PropertyTypeTokensBCTest.php
new file mode 100644
index 00000000..b743eaad
--- /dev/null
+++ b/Tests/Tokens/Collections/PropertyTypeTokensBCTest.php
@@ -0,0 +1,45 @@
+<?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\BackCompat\Helper;
+use PHPCSUtils\Tokens\Collections;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Test class.
+ *
+ * @covers \PHPCSUtils\Tokens\Collections::propertyTypeTokensBC
+ *
+ * @group collections
+ *
+ * @since 1.0.0
+ */
+class PropertyTypeTokensBCTest extends TestCase
+{
+
+    /**
+     * Test the method.
+     *
+     * @return void
+     */
+    public function testPropertyTypeTokensBC()
+    {
+        $version  = Helper::getVersion();
+        $expected = Collections::$propertyTypeTokens;
+
+        if (\version_compare($version, '3.99.99', '<=') === true) {
+            $expected[\T_ARRAY_HINT] = \T_ARRAY_HINT;
+        }
+
+        $this->assertSame($expected, Collections::propertyTypeTokensBC());
+    }
+}
diff --git a/Tests/Tokens/Collections/ReturnTypeTokensBCTest.php b/Tests/Tokens/Collections/ReturnTypeTokensBCTest.php
new file mode 100644
index 00000000..347ca673
--- /dev/null
+++ b/Tests/Tokens/Collections/ReturnTypeTokensBCTest.php
@@ -0,0 +1,50 @@
+<?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\BackCompat\Helper;
+use PHPCSUtils\Tokens\Collections;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Test class.
+ *
+ * @covers \PHPCSUtils\Tokens\Collections::returnTypeTokensBC
+ *
+ * @group collections
+ *
+ * @since 1.0.0
+ */
+class ReturnTypeTokensBCTest extends TestCase
+{
+
+    /**
+     * Test the method.
+     *
+     * @return void
+     */
+    public function testReturnTypeTokensBC()
+    {
+        $version  = Helper::getVersion();
+        $expected = Collections::$returnTypeTokens;
+
+        if (\version_compare($version, '3.99.99', '<=') === true) {
+            $expected[\T_RETURN_TYPE] = \T_RETURN_TYPE;
+            $expected[\T_ARRAY_HINT]  = \T_ARRAY_HINT;
+        }
+
+        if (\version_compare($version, '3.5.3', '<=') === true) {
+            $expected[\T_ARRAY] = \T_ARRAY;
+        }
+
+        $this->assertSame($expected, Collections::returnTypeTokensBC());
+    }
+}

From 12fdc0c43ef415b564d3904a24a92104716fc1f7 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Wed, 18 Mar 2020 06:29:37 +0100
Subject: [PATCH 2/4] BCFile/FunctionDeclarations::getMethodProperties():
 compatibility with PHPCS 4.x

This implements use of the `PHPCSUtils\Tokens\Collections::returnTypeTokensBC()` method in the `BCFile::getMethodProperties()` and the `FunctionDeclarations::getProperties()` methods to allow them to be cross-version compatible with PHPCS 2.6.0 - 4.x.
---
 PHPCSUtils/BackCompat/BCFile.php          | 3 ++-
 PHPCSUtils/Utils/FunctionDeclarations.php | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/PHPCSUtils/BackCompat/BCFile.php b/PHPCSUtils/BackCompat/BCFile.php
index d1cfc680..9220fc62 100644
--- a/PHPCSUtils/BackCompat/BCFile.php
+++ b/PHPCSUtils/BackCompat/BCFile.php
@@ -617,6 +617,7 @@ public static function getMethodProperties(File $phpcsFile, $stackPtr)
         $returnTypeToken    = false;
         $nullableReturnType = false;
         $hasBody            = true;
+        $returnTypeTokens   = Collections::returnTypeTokensBC();
 
         $parenthesisCloser = null;
         if (isset($tokens[$stackPtr]['parenthesis_closer']) === true) {
@@ -653,7 +654,7 @@ public static function getMethodProperties(File $phpcsFile, $stackPtr)
                     $nullableReturnType = true;
                 }
 
-                if (isset(Collections::$returnTypeTokens[$tokens[$i]['code']]) === true) {
+                if (isset($returnTypeTokens[$tokens[$i]['code']]) === true) {
                     if ($returnTypeToken === false) {
                         $returnTypeToken = $i;
                     }
diff --git a/PHPCSUtils/Utils/FunctionDeclarations.php b/PHPCSUtils/Utils/FunctionDeclarations.php
index e6e397bf..fbb0340a 100644
--- a/PHPCSUtils/Utils/FunctionDeclarations.php
+++ b/PHPCSUtils/Utils/FunctionDeclarations.php
@@ -266,6 +266,7 @@ public static function getProperties(File $phpcsFile, $stackPtr)
         $returnTypeEndToken = false;
         $nullableReturnType = false;
         $hasBody            = false;
+        $returnTypeTokens   = Collections::returnTypeTokensBC();
 
         $parenthesisCloser = null;
         if (isset($tokens[$stackPtr]['parenthesis_closer']) === true) {
@@ -306,7 +307,7 @@ public static function getProperties(File $phpcsFile, $stackPtr)
                     $nullableReturnType = true;
                 }
 
-                if (isset(Collections::$returnTypeTokens[$tokens[$i]['code']]) === true) {
+                if (isset($returnTypeTokens[$tokens[$i]['code']]) === true) {
                     if ($returnTypeToken === false) {
                         $returnTypeToken = $i;
                     }

From 73299d6e133bf6f1ad665204ea8e1d271d3b1609 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Wed, 18 Mar 2020 06:31:24 +0100
Subject: [PATCH 3/4] BCFile/Variables::getMemberProperties(): compatibility
 with PHPCS 4.x

This implements use of the `PHPCSUtils\Tokens\Collections::propertyTypeTokensBC()` method in the `BCFile::getMemberProperties()` and the `Variables::getMemberProperties()` methods to allow them to be cross-version compatible with PHPCS 2.6.0 - 4.x.
---
 PHPCSUtils/BackCompat/BCFile.php | 11 ++++++-----
 PHPCSUtils/Utils/Variables.php   | 11 ++++++-----
 2 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/PHPCSUtils/BackCompat/BCFile.php b/PHPCSUtils/BackCompat/BCFile.php
index 9220fc62..8ec9c3b7 100644
--- a/PHPCSUtils/BackCompat/BCFile.php
+++ b/PHPCSUtils/BackCompat/BCFile.php
@@ -834,10 +834,11 @@ public static function getMemberProperties(File $phpcsFile, $stackPtr)
             }
         }
 
-        $type         = '';
-        $typeToken    = false;
-        $typeEndToken = false;
-        $nullableType = false;
+        $type               = '';
+        $typeToken          = false;
+        $typeEndToken       = false;
+        $nullableType       = false;
+        $propertyTypeTokens = Collections::propertyTypeTokensBC();
 
         if ($i < $stackPtr) {
             // We've found a type.
@@ -854,7 +855,7 @@ public static function getMemberProperties(File $phpcsFile, $stackPtr)
                     $nullableType = true;
                 }
 
-                if (isset(Collections::$propertyTypeTokens[$tokens[$i]['code']]) === true) {
+                if (isset($propertyTypeTokens[$tokens[$i]['code']]) === true) {
                     $typeEndToken = $i;
                     if ($typeToken === false) {
                         $typeToken = $i;
diff --git a/PHPCSUtils/Utils/Variables.php b/PHPCSUtils/Utils/Variables.php
index fee9b535..c420943f 100644
--- a/PHPCSUtils/Utils/Variables.php
+++ b/PHPCSUtils/Utils/Variables.php
@@ -163,10 +163,11 @@ public static function getMemberProperties(File $phpcsFile, $stackPtr)
             }
         }
 
-        $type         = '';
-        $typeToken    = false;
-        $typeEndToken = false;
-        $nullableType = false;
+        $type               = '';
+        $typeToken          = false;
+        $typeEndToken       = false;
+        $nullableType       = false;
+        $propertyTypeTokens = Collections::propertyTypeTokensBC();
 
         if ($i < $stackPtr) {
             // We've found a type.
@@ -183,7 +184,7 @@ public static function getMemberProperties(File $phpcsFile, $stackPtr)
                     $nullableType = true;
                 }
 
-                if (isset(Collections::$propertyTypeTokens[$tokens[$i]['code']]) === true) {
+                if (isset($propertyTypeTokens[$tokens[$i]['code']]) === true) {
                     $typeEndToken = $i;
                     if ($typeToken === false) {
                         $typeToken = $i;

From 1737d224cdb0d5aa63c65c1fc5da7dd1b7eb7224 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Wed, 18 Mar 2020 06:32:29 +0100
Subject: [PATCH 4/4] FunctionDeclarations::getArrowFunctionOpenClose():
 compatibility with PHPCS 4.x

This implements use of the `PHPCSUtils\Tokens\Collections::returnTypeTokensBC()` method in the `FunctionDeclarations::getArrowFunctionOpenClose()` method to allow it to be cross-version compatible with PHPCS 2.6.0 - 4.x.
---
 PHPCSUtils/Utils/FunctionDeclarations.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/PHPCSUtils/Utils/FunctionDeclarations.php b/PHPCSUtils/Utils/FunctionDeclarations.php
index fbb0340a..edf222e1 100644
--- a/PHPCSUtils/Utils/FunctionDeclarations.php
+++ b/PHPCSUtils/Utils/FunctionDeclarations.php
@@ -713,7 +713,7 @@ public static function getArrowFunctionOpenClose(File $phpcsFile, $stackPtr)
         $returnValue['parenthesis_closer'] = $tokens[$nextNonEmpty]['parenthesis_closer'];
 
         $ignore                 = Tokens::$emptyTokens;
-        $ignore                += Collections::$returnTypeTokens;
+        $ignore                += Collections::returnTypeTokensBC();
         $ignore[\T_COLON]       = \T_COLON;
         $ignore[\T_INLINE_ELSE] = \T_INLINE_ELSE; // Return type colon on PHPCS < 2.9.1.
         $ignore[\T_INLINE_THEN] = \T_INLINE_THEN; // Nullable type indicator on PHPCS < 2.9.1.