Tokens\Collections: new methods for improved compatibility with PHPCS 4.x

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;
                     }
@@ -833,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.
@@ -853,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;

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;
+    }
 }

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;
                     }
@@ -712,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.

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;

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());
+    }
+}

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());
+    }
+}