Collections: deprecate $textStingStartTokens in favour of textStingSt…

…artTokens()

Over the last three PHP versions, PHP has steadily kept on introducing new tokens.

In the context of this class, the introduction of a new token means that a collection can no longer be a property and must be changed to a method with some logic instead.

With this in mind, all properties in the `Collections` class are being deprecated in favour of methods, to prevent the BC-breaks this kind of change would cause if left till later.

The deprecated properties will be removed (or made `private`) before the `1.0.0` version is tagged. The deprecation in the upcoming alpha gives standards which have started to implement the use of PHPCSUtils a little time to switch over though.

Includes only a perfunctory unit test for the new method, as the `textStingStartTokens()` method doesn't contain any actual logic.
For now, it is just safeguarded that a) the method is available and can be called and b) that the method is in line with the now deprecated property.

Includes replacing any references to this property in the PHPCSUtils codebase to now call the function instead.

PHPCSUtils/Tokens/Collections.php

@@ -472,9 +472,11 @@ class Collections
     ];
 
     /**
-     * Tokens which can start a - potentially multi-line - text string.
+     * DEPRECATED: Tokens which can start a - potentially multi-line - text string.
+     *
+     * @since 1.0.0-alpha1
      *
-     * @since 1.0.0
+     * @deprecated 1.0.0-alpha4 Use the {@see Collections::textStingStartTokens()} method instead.
      *
      * @var array <int|string> => <int|string>
      */
@@ -1398,4 +1400,16 @@ public static function shortListTokensBC()
     {
         return self::$shortListTokensBC;
     }
+
+    /**
+     * Tokens which can start a - potentially multi-line - text string.
+     *
+     * @since 1.0.0-alpha4 This method replaces the {@see Collections::$textStingStartTokens} property.
+     *
+     * @return array <int|string> => <int|string>
+     */
+    public static function textStingStartTokens()
+    {
+        return self::$textStingStartTokens;
+    }
 }

PHPCSUtils/Utils/TextStrings.php

@@ -55,7 +55,7 @@ public static function getCompleteTextString(File $phpcsFile, $stackPtr, $stripQ
         $tokens = $phpcsFile->getTokens();
 
         // Must be the start of a text string token.
-        if (isset($tokens[$stackPtr], Collections::$textStingStartTokens[$tokens[$stackPtr]['code']]) === false) {
+        if (isset($tokens[$stackPtr], Collections::textStingStartTokens()[$tokens[$stackPtr]['code']]) === false) {
             throw new RuntimeException(
                 '$stackPtr must be of type T_START_HEREDOC, T_START_NOWDOC, T_CONSTANT_ENCAPSED_STRING'
                 . ' or T_DOUBLE_QUOTED_STRING'

Tests/Tokens/Collections/ArrayOpenTokensBCTest.php

@@ -12,6 +12,7 @@
 
 use PHPCSUtils\Tokens\Collections;
 use PHPUnit\Framework\TestCase;
+use Yoast\PHPUnitPolyfills\Polyfills\AssertIsType;
 
 /**
  * Test class.
@@ -24,6 +25,7 @@
  */
 class ArrayOpenTokensBCTest extends TestCase
 {
+    use AssertIsType;
 
     /**
      * Test the method.

Tests/Tokens/Collections/TextStingStartTokensTest.php

@@ -0,0 +1,37 @@
+<?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::textStingStartTokens
+ *
+ * @group collections
+ *
+ * @since 1.0.0
+ */
+class TextStingStartTokensTest extends TestCase
+{
+
+    /**
+     * Test the method.
+     *
+     * @return void
+     */
+    public function testTextStingStartTokens()
+    {
+        $this->assertSame(Collections::$textStingStartTokens, Collections::textStingStartTokens());
+    }
+}