Tokens\Collections: add two new methods

* `functionDeclarationTokens()` returning the tokens which can represent a keyword which starts a function declaration.
* `functionDeclarationTokensBC()` same, but allowing for BC down to PHPCS 2.6.0 (arrow functions).

Includes unit tests.

Author: jrfnl

PHPCSUtils/Tokens/Collections.php

@@ -531,6 +531,72 @@ public static function arrowFunctionTokensBC()
         return $tokens;
     }
 
+    /**
+     * Tokens which can represent a keyword which starts a function declaration.
+     *
+     * Note: this is a method, not a property as the `T_FN` token may not exist.
+     *
+     * Sister-method to the `functionDeclarationTokensBC()` method.
+     * This  method supports PHPCS 3.5.3 and up.
+     * The `functionDeclarationTokensBC()` method supports PHPCS 2.6.0 and up.
+     *
+     * @see \PHPCSUtils\Tokens\Collections::functionDeclarationTokensBC() Related method (PHPCS 2.6.0+).
+     *
+     * @since 1.0.0
+     *
+     * @return array <int|string> => <int|string>
+     */
+    public static function functionDeclarationTokens()
+    {
+        $tokens = [
+            \T_FUNCTION => \T_FUNCTION,
+            \T_CLOSURE  => \T_CLOSURE,
+        ];
+
+        if (\defined('T_FN') === true) {
+            // PHP 7.4 or PHPCS 3.5.3+.
+            $tokens[\T_FN] = \T_FN;
+        }
+
+        return $tokens;
+    }
+
+    /**
+     * Tokens which can represent a keyword which starts a function declaration.
+     *
+     * Note: this is a method, not a property as the `T_FN` token may not exist.
+     *
+     * Sister-method to the `functionDeclarationTokens()` method.
+     * The `functionDeclarationTokens()` method supports PHPCS 3.5.3 and up.
+     * This method supports PHPCS 2.6.0 and up.
+     *
+     * Notable difference:
+     * This method accounts for when the `T_FN` token doesn't exist.
+     * Note: if this method is used, the `FunctionDeclarations::isArrowFunction() method
+     * needs to be used on arrow function tokens to verify whether it really is an arrow function
+     * declaration or not.
+     *
+     * It is recommended to use the method instead of the property if a standard supports PHPCS < 3.3.0.
+     *
+     * @see \PHPCSUtils\Tokens\Collections::functionDeclarationTokens() Related method (PHPCS 3.5.3+).
+     * @see \PHPCSUtils\Tokens\FunctionDeclarations::isArrowFunction()  Arrow function verification.
+     *
+     * @since 1.0.0
+     *
+     * @return array <int|string> => <int|string>
+     */
+    public static function functionDeclarationTokensBC()
+    {
+        $tokens = [
+            \T_FUNCTION => \T_FUNCTION,
+            \T_CLOSURE  => \T_CLOSURE,
+        ];
+
+        $tokens += self::arrowFunctionTokensBC();
+
+        return $tokens;
+    }
+
     /**
      * Token types which can be encountered in a parameter type declaration (cross-version).
      *

Tests/Tokens/Collections/FunctionDeclarationTokensBCTest.php

@@ -0,0 +1,51 @@
+<?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::functionDeclarationTokensBC
+ *
+ * @group collections
+ *
+ * @since 1.0.0
+ */
+class FunctionDeclarationTokensBCTest extends TestCase
+{
+
+    /**
+     * Test the method.
+     *
+     * @return void
+     */
+    public function testFunctionDeclarationTokensBC()
+    {
+        $version  = Helper::getVersion();
+        $expected = [
+            \T_FUNCTION => \T_FUNCTION,
+            \T_CLOSURE  => \T_CLOSURE,
+            \T_STRING   => \T_STRING,
+        ];
+
+        if (\version_compare($version, '3.5.3', '>=') === true
+            || \version_compare(\PHP_VERSION_ID, '70399', '>=') === true
+        ) {
+            $expected[\T_FN] = \T_FN;
+        }
+
+        $this->assertSame($expected, Collections::functionDeclarationTokensBC());
+    }
+}

Tests/Tokens/Collections/FunctionDeclarationTokensTest.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::functionDeclarationTokens
+ *
+ * @group collections
+ *
+ * @since 1.0.0
+ */
+class FunctionDeclarationTokensTest extends TestCase
+{
+
+    /**
+     * Test the method.
+     *
+     * @return void
+     */
+    public function testFunctionDeclarationTokens()
+    {
+        $version  = Helper::getVersion();
+        $expected = [
+            \T_FUNCTION => \T_FUNCTION,
+            \T_CLOSURE  => \T_CLOSURE,
+        ];
+
+        if (\version_compare($version, '3.5.3', '>=') === true
+            || \version_compare(\PHP_VERSION_ID, '70399', '>=') === true
+        ) {
+            $expected[\T_FN] = \T_FN;
+        }
+
+        $this->assertSame($expected, Collections::functionDeclarationTokens());
+    }
+}