PHPCS: switch to phpcsdevcs (#259)

* Composer: require PHPCSDevCS

* PHPCS: switch to using the PHPCSDev standard

This commit:
* Switches out the `PSR2` ruleset in favour of the `PHPCSDev` ruleset.
    The PHPCSDev ruleset checks the following:
    > * Compliance with PSR-12, with a few select exceptions.
    > * Use of camelCase variable and function names.
    > * Use of normalized arrays.
    > * All files, classes, functions and properties are documented with a docblock and contain the minimally needed information.
    > * A number of arbitrary additional code style and QA checks.
    > * PHP cross-version compatibility, while allowing for tokens back-filled by PHPCS itself.
* For the PHP cross-version compatibility check, the minimum supported PHP version (`testVersion`) is set to PHP 5.4, in line with the `require`ment for this package per the `composer.json` file.
* In contrast to `PHPCSDev`/PSR12, the ruleset for the VariableAnalysis package will:
    - Enforce tabs instead of spaces.
    - Disallow a blank line at the start of a class.
        Note: this complies with PSR12. PHPCSDev already had the blank line enforcement in place prior to this being forbidden via the PSR12 standard, which is why it excludes the rule.
    - Not enforce most documentation checks.
    - Not enforce assignment operator alignment.
* Additionally, for the time being, the PSR12 line length guidelines will not be enforced.
    Enforcing those needs additional (manual) adjustments to the codebase which can be done at a later point in time.
* Adds some extra documention to the ruleset.

Refs:
* https://github.com/PHPCSStandards/PHPCSDevCS
* https://github.com/PHPCSStandards/PHPCSDevCS/blob/main/PHPCSDev/ruleset.xml

* CS: various minor whitespace fixes

Minimal changes needed to comply with the PSR12/PHPCSDev whitespace rules.

Most notably this commit adds a blank line between a PHP open tag and the namespace declaration as per the PSR12 file header rules.

* CS: minor code restructuring [1]

The `VariableAnalysisSniff::processVariableAsSuperGlobal()` method checks a variable name against a fixed array of names using `in_array()`.

To comply with the updated CS rules, each parameter in the function call would need to be placed on a new line and the function call itself as well, making this a very drawn out condition.

By restructuring the code to declare the array prior to the `in_array()` function call, this is no longer needed.

Additional notes:
* I've also changed the `in_array()` call to a _strict_ comparison by adding the third parameter and setting it to `true`.
* I've simplified the `return` by removing the unnecessary condition and double return statements.
* The array could/should probably be declared as a property instead of within the function.
    I've not done so at this time, as it could also be considered to switch over to using the PHPCSUtils `Variables::isSuperglobal()` or `Variables::isSuperglobalName()` methods in the future.

Ref:
* https://www.php.net/manual/en/function.in-array.php
* https://phpcsutils.com/phpdoc/classes/PHPCSUtils-Utils-Variables.html#property_phpReservedVars

* CS: minor code restructuring [2]

Similar to the previous commit, the `VariableAnalysisSniff::processVariableAsStaticDeclaration()` method declares an array within a function call.

This commit moves the array declaration out of the function call and leverages a pre-defined array from the PHPCS native `Tokens` class to retrieve a number of the tokens (heredoc and nowdoc tokens).

Note: this commit does **not** fix known shortcomings of this method as reported in 158 and 253.

Co-authored-by: jrfnl <jrfnl@users.noreply.github.com>

.github/workflows/test.yml

@@ -147,8 +147,8 @@ jobs:
 
       - name: 'Composer: adjust dependencies'
         run: |
-          # Remove dev dependencies which are not compatible with all supported PHP versions.
-          composer remove --dev --no-update sirbrillig/phpcs-import-detection phpstan/phpstan
+          # Remove dev dependencies which are not compatible with all supported PHP/PHPCS versions.
+          composer remove --dev --no-update phpcsstandards/phpcsdevcs sirbrillig/phpcs-import-detection phpstan/phpstan
           composer require --no-update squizlabs/php_codesniffer:"${{ matrix.phpcs_version }}"
 
       - name: Install Composer dependencies

Tests/BaseTestCase.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests;
 
 use PHPUnit\Framework\TestCase;

Tests/VariableAnalysisSniff/ArrayAssignmentShortcutTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/ArrowFunctionTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/ClosingPhpTagsTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/GlobalScopeTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/IfConditionTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/IssetTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/UnsetTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/UnusedFollowedByRequireTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/VariableAnalysisTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/VariableArgumentListTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/VariableAnalysisSniff/WhileLoopTest.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace VariableAnalysis\Tests\VariableAnalysisSniff;
 
 use VariableAnalysis\Tests\BaseTestCase;

Tests/bootstrap.php

@@ -1,3 +1,4 @@
 <?php
+
 require_once __DIR__ . '/../vendor/squizlabs/php_codesniffer/tests/bootstrap.php';
 require_once __DIR__ . '/BaseTestCase.php';

VariableAnalysis/Lib/Helpers.php

@@ -31,7 +31,7 @@ public static function getPossibleEndOfFileTokens()
 	 */
 	public static function getIntOrNull($value)
 	{
-		return is_int($value) ? $value: null;
+		return is_int($value) ? $value : null;
 	}
 
 	/**

VariableAnalysis/Sniffs/CodeAnalysis/VariableAnalysisSniff.php

@@ -378,7 +378,7 @@ protected function getOrCreateScopeInfo($currScope)
 	protected function getVariableInfo($varName, $currScope)
 	{
 		$scopeInfo = $this->getScopeInfo($currScope);
-		return ( $scopeInfo && isset($scopeInfo->variables[$varName]) ) ? $scopeInfo->variables[$varName] : null;
+		return ($scopeInfo && isset($scopeInfo->variables[$varName])) ? $scopeInfo->variables[$varName] : null;
 	}
 
 	/**
@@ -838,8 +838,7 @@ protected function processVariableAsThisWithinClass(File $phpcsFile, $stackPtr,
 	 */
 	protected function processVariableAsSuperGlobal($varName)
 	{
-		// Are we a superglobal variable?
-		if (in_array($varName, [
+		$superglobals = [
 			'GLOBALS',
 			'_SERVER',
 			'_GET',
@@ -854,11 +853,9 @@ protected function processVariableAsSuperGlobal($varName)
 			'php_errormsg',
 			'http_response_header',
 			'HTTP_RAW_POST_DATA',
-		])) {
-			return true;
-		}
-
-		return false;
+		];
+		// Are we a superglobal variable?
+		return (in_array($varName, $superglobals, true));
 	}
 
 	/**
@@ -1140,22 +1137,21 @@ protected function processVariableAsStaticDeclaration(File $phpcsFile, $stackPtr
 		//   class constant T_STRING T_DOUBLE_COLON T_STRING
 		// Search backwards for first token that isn't whitespace, comma, variable,
 		// equals, or on the list of assignable constant values above.
-		$staticPtr = $phpcsFile->findPrevious(
-			[
-				T_WHITESPACE, T_VARIABLE, T_COMMA, T_EQUAL,
-				T_MINUS, T_LNUMBER, T_DNUMBER,
-				T_CONSTANT_ENCAPSED_STRING,
-				T_STRING,
-				T_DOUBLE_COLON,
-				T_START_HEREDOC, T_HEREDOC, T_END_HEREDOC,
-				T_START_NOWDOC, T_NOWDOC, T_END_NOWDOC,
-			],
-			$stackPtr - 1,
-			null,
-			true,
-			null,
-			true
-		);
+		$find = [
+			T_WHITESPACE => T_WHITESPACE,
+			T_VARIABLE => T_VARIABLE,
+			T_COMMA => T_COMMA,
+			T_EQUAL => T_EQUAL,
+			T_MINUS => T_MINUS,
+			T_LNUMBER => T_LNUMBER,
+			T_DNUMBER => T_DNUMBER,
+			T_CONSTANT_ENCAPSED_STRING => T_CONSTANT_ENCAPSED_STRING,
+			T_STRING => T_STRING,
+			T_DOUBLE_COLON => T_DOUBLE_COLON,
+		];
+		$find += Tokens::$heredocTokens;
+
+		$staticPtr = $phpcsFile->findPrevious($find, $stackPtr - 1, null, true, null, true);
 		if (($staticPtr === false) || ($tokens[$staticPtr]['code'] !== T_STATIC)) {
 			return false;
 		}

composer.json

@@ -49,6 +49,7 @@
     "require-dev": {
         "phpunit/phpunit": "^4.8.36 || ^5.7.21 || ^6.5 || ^7.0 || ^8.0 || ^9.0",
         "sirbrillig/phpcs-import-detection": "^1.1",
+        "phpcsstandards/phpcsdevcs": "^1.1",
         "phpstan/phpstan": "^1.7",
         "dealerdirect/phpcodesniffer-composer-installer": "^0.7.0"
     }

phpcs.xml.dist

@@ -1,7 +1,15 @@
 <?xml version="1.0"?>
 <ruleset name="PaytonsStandard">
-    <file>./VariableAnalysis/</file>
-    <file>./Tests/</file>
+
+    <!--
+    #############################################################################
+    COMMAND LINE ARGUMENTS
+    https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
+    #############################################################################
+    -->
+
+    <file>.</file>
+
     <exclude-pattern>./Tests/VariableAnalysisSniff/fixtures/</exclude-pattern>
     <exclude-pattern>./vendor/</exclude-pattern>
 
@@ -17,21 +25,83 @@
     <!-- Check up to 8 files simultaneously. -->
     <arg name="parallel" value="8"/>
 
+    <!-- One tab = 4 spaces. This is needed to properly support tab indentation. -->
     <arg name="tab-width" value="4"/>
 
-    <!-- Rules -->
-    <rule ref="PSR2">
+    <!--
+    #############################################################################
+    USE THE PHPCSDev, ImportDetection and VariableAnalysis RULESETS
+    #############################################################################
+    -->
+
+    <!-- Set minimum PHP version supported to PHP 5.4. -->
+    <config name="testVersion" value="5.4-"/>
+
+    <rule ref="PHPCSDev">
+        <!-- This code base uses tab indentation instead of spaces. -->
         <exclude name="Generic.WhiteSpace.DisallowTabIndent"/>
+
+        <!-- Don't enforce lining up the assignment operators in assignment blocks. -->
+        <exclude name="Generic.Formatting.MultipleStatementAlignment.NotSameWarning"/>
+
+        <!-- Don't enforce lining up the double arrows in array declarations.
+             Possibly enforce this later once the sniff has been replaced by a better, more configurable version. -->
+        <exclude name="Squiz.Arrays.ArrayDeclaration.DoubleArrowNotAligned"/>
+
+        <!-- Don't enforce documentation (yet). -->
+        <exclude name="Generic.Commenting.DocComment"/>
+        <exclude name="PEAR.Commenting.ClassComment"/>
+        <exclude name="PEAR.Commenting.FileComment"/>
+        <exclude name="PEAR.Commenting.InlineComment"/>
+
+        <!-- WIP: This is part of PSR12 and should probably be enforced,
+             but the codebase needs work before it can be enabled. -->
         <exclude name="Generic.Files.LineLength.TooLong" />
     </rule>
 
-    <rule ref="Generic.WhiteSpace.DisallowSpaceIndent"/>
+    <rule ref="ImportDetection" />
+    <rule ref="VariableAnalysis"/>
+
+
+    <!--
+    #############################################################################
+    SNIFF SPECIFIC CONFIGURATION AND SELECTIVELY DEVIATE FROM THE STANDARD
+    #############################################################################
+    -->
+
+    <!-- Enforce the use of tab indentation instead of spaces. -->
+    <rule name="Generic.WhiteSpace.DisallowSpaceIndent"/>
     <rule ref="Generic.WhiteSpace.ScopeIndent">
         <properties>
             <property name="tabIndent" value="true"/>
         </properties>
     </rule>
 
-    <rule ref="ImportDetection" />
-    <rule ref="VariableAnalysis"/>
+    <!-- Disallow a blank line at the start of a class.
+         This is a minor deviation from PHPCSDev to stay closer to PSR12. -->
+    <rule ref="PSR12.Classes.OpeningBraceSpace.Found">
+        <severity>5</severity>
+    </rule>
+    <rule ref="Squiz.WhiteSpace.FunctionSpacing">
+        <properties>
+            <property name="spacingBeforeFirst" value="0"/>
+        </properties>
+    </rule>
+    <rule ref="Squiz.WhiteSpace.MemberVarSpacing">
+        <properties>
+            <property name="spacingBeforeFirst" value="0"/>
+        </properties>
+    </rule>
+
+    <!-- While (most of) the documentation sniffs included in PHPCSDev are disabled,
+         do enforce some basic checking on the tags in function docblocks, like
+         enforcing columnization of the information in @param tags. -->
+    <rule ref="PEAR.Commenting.FunctionComment">
+        <exclude name="PEAR.Commenting.FunctionComment.MissingParamTag"/>
+        <exclude name="PEAR.Commenting.FunctionComment.MissingParamComment"/>
+        <exclude name="PEAR.Commenting.FunctionComment.InvalidThrows"/>
+        <exclude name="PEAR.Commenting.FunctionComment.MissingReturn"/>
+        <exclude name="PEAR.Commenting.FunctionComment.Missing"/>
+    </rule>
+
 </ruleset>