From 6511b3e849b36ff776ae3012185534769c06c18c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Denis=20=C5=BDoljom?= <dingo-d@users.noreply.github.com>
Date: Sat, 27 Aug 2022 18:48:28 +0200
Subject: [PATCH] Add new sniff that checks the declare statements

---
 .../DeclareStatementsStyleStandard.xml        |  50 ++
 .../DeclareStatementsStyleSniff.php           | 241 +++++++++
 .../DeclareStatementsStyleUnitTest.inc        | 481 ++++++++++++++++++
 .../DeclareStatementsStyleUnitTest.php        |  78 +++
 4 files changed, 850 insertions(+)
 create mode 100644 Universal/Docs/DeclareStatements/DeclareStatementsStyleStandard.xml
 create mode 100644 Universal/Sniffs/DeclareStatements/DeclareStatementsStyleSniff.php
 create mode 100644 Universal/Tests/DeclareStatements/DeclareStatementsStyleUnitTest.inc
 create mode 100644 Universal/Tests/DeclareStatements/DeclareStatementsStyleUnitTest.php

diff --git a/Universal/Docs/DeclareStatements/DeclareStatementsStyleStandard.xml b/Universal/Docs/DeclareStatements/DeclareStatementsStyleStandard.xml
new file mode 100644
index 0000000..9adfd58
--- /dev/null
+++ b/Universal/Docs/DeclareStatements/DeclareStatementsStyleStandard.xml
@@ -0,0 +1,50 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Declare Statements Style"
+    >
+    <standard>
+    <![CDATA[
+        Declare statements should, by default, be written without curly braces/alternative syntax.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Declare statement written without curly braces.">
+        <![CDATA[
+declare(strict_types=1);
+        ]]>
+        </code>
+        <code title="Invalid: Declare statement written with curly braces or alternative syntax.">
+        <![CDATA[
+declare(encoding='ISO-8859-1', ticks=1) {
+    // Code.
+}
+
+declare(encoding='ISO-8859-1', ticks=10):
+    declare(ticks=1):
+    // Code.
+    enddeclare;
+enddeclare;
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+        strict_types declaration directive mustn't be written using curly braces, or with alternative syntax.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: strict_types written without curly braces.">
+        <![CDATA[
+declare(strict_types=1);
+        ]]>
+        </code>
+        <code title="Invalid: strict_types written using alternative syntax/curly braces.">
+        <![CDATA[
+declare(strict_types=1, ticks=1) {
+   // Code.
+}
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>
diff --git a/Universal/Sniffs/DeclareStatements/DeclareStatementsStyleSniff.php b/Universal/Sniffs/DeclareStatements/DeclareStatementsStyleSniff.php
new file mode 100644
index 0000000..6448820
--- /dev/null
+++ b/Universal/Sniffs/DeclareStatements/DeclareStatementsStyleSniff.php
@@ -0,0 +1,241 @@
+<?php
+/**
+ * PHPCSExtra, a collection of sniffs and standards for use with PHP_CodeSniffer.
+ *
+ * @package   PHPCSExtra
+ * @copyright 2020 PHPCSExtra Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSExtra
+ */
+
+namespace PHPCSExtra\Universal\Sniffs\DeclareStatements;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PHP_CodeSniffer\Util\Tokens;
+use PHPCSUtils\Utils\TextStrings;
+
+/**
+ * Checks the style of the declare statement
+ *
+ * `declare` directive can be written in different styles:
+ * 1. Applied to the rest of the file, usually written at the top of a file like `declare(strict_types=1);`
+ * 2. Applied to a limited scope using curly braces (the exception to this rule is the `strict_types` directive)
+ * 3. Applied to a limited scope using alternative control structure syntax
+ *
+ * You can also have multiple directives written inside the `declare` directive.
+ * This sniff will check the style of the `declare` directive - by default applied to all directives,
+ * written without braces.
+ *
+ * You can modify the sniff by changing the `declareStyle` option to require or disallow braces,
+ * and require or allow the style to only one of the two directives (`ticks` and `encoding`).
+ *
+ * @since 1.0.0
+ */
+class DeclareStatementsStyleSniff implements Sniff
+{
+
+    /**
+     * Whether to require curly brace style or disallow it
+     * when using declare statements.
+     *
+     * Possible values: requireBraces, disallowBraces.
+     *
+     * Default is disallowBraces.
+     *
+     * @var string
+     */
+    public $declareStyle = 'disallowBraces';
+
+    /**
+     * Which declare to enforce the brace style for.
+     * If not explicitly defined, the brace style will be applied
+     * to all declare directive.
+     *
+     * The exception is the strict_types directive which cannot be
+     * written using curly braces.
+     *
+     * Possible values: ticks, encoding.
+     *
+     * @var array
+     */
+    public $directiveType = [];
+
+    /**
+     * Allowed declare directives.
+     *
+     * @var array
+     */
+    private $allowedDirectives = [
+        'strict_types',
+        'ticks',
+        'encoding',
+    ];
+
+    /**
+     * Returns an array of tokens this test wants to listen for.
+     *
+     * @since 1.0.0
+     *
+     * @return array
+     */
+    public function register()
+    {
+        return [
+            T_DECLARE
+        ];
+    }
+
+    /**
+     * Processes this test, when one of its tokens is encountered.
+     *
+     * @since 1.0.0
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     * @param int                         $stackPtr  The position of the current token
+     *                                               in the stack passed in $tokens.
+     *
+     * @return void
+     */
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        $openParenPtr  = $tokens[$stackPtr]['parenthesis_opener'];
+        $closeParenPtr = $tokens[$stackPtr]['parenthesis_closer'];
+
+        if (isset($openParenPtr, $closeParenPtr) === false) {
+            // Parse error or live coding, bow out.
+            return;
+        }
+
+        $directiveStrings = [];
+        // Get the next string and check if it's an allowed directive.
+        // Find all the directive strings inside the declare statement.
+        for ($i = $openParenPtr; $i <= $closeParenPtr; $i++) {
+            if ($tokens[$i]['code'] === \T_STRING) {
+                $directiveStrings[] = $tokens[$i]['content'];
+            }
+        }
+
+        foreach ($directiveStrings as $directiveString) {
+            if (!in_array($directiveString, $this->allowedDirectives, true)) {
+                $phpcsFile->addError(
+                    sprintf(
+                        'Declare directives can be one of: %1$s. "%2$s" found.',
+                        implode(', ', $this->allowedDirectives),
+                        $directiveString
+                    ),
+                    $stackPtr,
+                    'WrongDeclareDirective'
+                );
+                return;
+            }
+            unset($directiveString);
+        }
+
+        // Curly braces.
+        $hasScopeOpenerCloser = isset($tokens[$stackPtr]['scope_opener']);
+
+        // If strict types is defined using curly brace, throw error.
+        if ($hasScopeOpenerCloser !== false && in_array('strict_types', $directiveStrings, true)) {
+            $phpcsFile->addError(
+                sprintf(
+                    'strict_types declaration must not use block mode. Opening brace found on line %d',
+                    $tokens[$stackPtr]['line']
+                ),
+                $stackPtr,
+                'Forbidden'
+            );
+            return;
+        }
+
+        // Fix for the case when the code is between the curly braces for the strict_types.
+        $codePtr = $phpcsFile->findNext(Tokens::$emptyTokens, ($closeParenPtr + 1), null, true);
+
+        /* If the code pointer is not one of:
+         *    \T_SEMICOLON, \T_CLOSE_TAG or \T_OPEN_CURLY_BRACKET, \T_COLON
+         * throw an error.
+         */
+        if (!in_array($tokens[$codePtr]['code'], [\T_SEMICOLON, \T_CLOSE_TAG, \T_OPEN_CURLY_BRACKET, \T_COLON], true)) {
+            $phpcsFile->addError(
+                'Unexpected code found after opening the declare statement without closing it.',
+                $stackPtr,
+                'UnexpectedCodeFound'
+            );
+            return;
+        }
+
+        if ($this->declareStyle === 'requireBraces' &&
+            $hasScopeOpenerCloser === false &&
+            in_array('strict_types', $directiveStrings, true)
+        ) {
+            $phpcsFile->addError(
+                'strict_types declaration is not compatible with requireBraces option.',
+                $stackPtr,
+                'IncompatibleCurlyBracesRequirement'
+            );
+            return;
+        }
+
+        if ($this->declareStyle === 'disallowBraces' && $hasScopeOpenerCloser !== false) {
+            $phpcsFile->addError('Declare statement found using curly braces', $stackPtr, 'DisallowedCurlyBraces');
+            return;
+        }
+
+        if (in_array('ticks', $this->directiveType, true)) {
+            if ($this->declareStyle === 'requireBraces' &&
+                $hasScopeOpenerCloser === false &&
+                in_array('ticks', $directiveStrings, true)
+            ) {
+                $phpcsFile->addError(
+                    'Declare statement for found without curly braces',
+                    $stackPtr,
+                    'MissingCurlyBracesTicks'
+                );
+                return;
+            }
+
+            if ($this->declareStyle === 'disallowBraces' && $hasScopeOpenerCloser !== false) {
+                $phpcsFile->addError(
+                    'Declare statement found using curly braces',
+                    $stackPtr,
+                    'DisallowedCurlyBracesTicks'
+                );
+                return;
+            }
+        }
+
+        if (in_array('encoding', $this->directiveType, true)) {
+            if ($this->declareStyle === 'requireBraces' &&
+                $hasScopeOpenerCloser === false &&
+                in_array('encoding', $directiveStrings, true)
+            ) {
+                $phpcsFile->addError(
+                    'Declare statement found without curly braces',
+                    $stackPtr,
+                    'MissingCurlyBracesEncoding'
+                );
+                return;
+            }
+
+            if ($this->declareStyle === 'disallowBraces' && $hasScopeOpenerCloser !== false) {
+                $phpcsFile->addError(
+                    'Declare statement found using curly braces',
+                    $stackPtr,
+                    'DisallowedCurlyBracesEncoding'
+                );
+                return;
+            }
+        }
+
+        if ($this->declareStyle === 'requireBraces' &&
+            $hasScopeOpenerCloser === false &&
+            empty($this->directiveType) &&
+            !in_array('strict_types', $directiveStrings, true)
+        ) {
+            $phpcsFile->addError('Declare statement found without curly braces', $stackPtr, 'MissingCurlyBraces');
+            return;
+        }
+    }
+}
diff --git a/Universal/Tests/DeclareStatements/DeclareStatementsStyleUnitTest.inc b/Universal/Tests/DeclareStatements/DeclareStatementsStyleUnitTest.inc
new file mode 100644
index 0000000..6d9b84d
--- /dev/null
+++ b/Universal/Tests/DeclareStatements/DeclareStatementsStyleUnitTest.inc
@@ -0,0 +1,481 @@
+<?php
+
+/* Test the defaults (no braces/alternative syntax, all directives). */
+
+declare(strict_types=1); // Ok.
+
+declare(ticks=10); // Ok.
+
+declare(encoding='ISO-8859-1'); // Ok.
+
+declare(strict_types=1, encoding='ISO-8859-1'); // Ok.
+
+/* Always error if `strict_types` use braces or alternative syntax (alone and with other directive). */
+
+declare(strict_types=1) { // Error.
+
+}
+
+declare(strict_types=1, ticks=10) { // Error.
+
+}
+
+declare(strict_types=1) // Error.
+
+
+{
+// Code.
+
+
+}
+
+declare(strict_types=1) // Error.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(strict_types=1): // Error.
+// Code.
+enddeclare;
+
+declare(strict_types=1, ticks=10): // Error.
+// Code.
+enddeclare;
+
+declare(ticks=1): // Error.
+    declare(ticks=1): // Error.
+    // Code.
+    enddeclare;
+enddeclare;
+
+declare(encoding='ISO-8859-1', ticks=10): // Error.
+    declare(ticks=1): // Error.
+    // Code.
+    enddeclare;
+enddeclare;
+
+/* Error if braces/alternative syntax are used. */
+
+declare(ticks=1) { // Error.
+
+}
+
+declare(ticks=1) // Error.
+
+
+{
+// Code.
+
+
+}
+
+declare(ticks=1) // Error.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(ticks=1): // Error.
+// Code.
+enddeclare;
+
+declare(encoding='ISO-8859-1', ticks=10): // Error.
+// Code.
+enddeclare;
+
+/* Throw errors if braces are used but also if some code is written before braces (unexpected code). */
+
+declare(ticks=1) // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1', ticks=10) // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+
+/* Test the required braces/alternative syntax for all directives. */
+// phpcs:set Universal.DeclareStatements.DeclareStatementsStyle declareStyle requireBraces
+
+declare(ticks=1) { // Ok.
+
+}
+
+declare(ticks=1) // Ok.
+
+
+{
+// Code.
+
+
+}
+
+declare(ticks=1) // Ok.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1') { // Ok.
+
+}
+
+declare(encoding='ISO-8859-1') // Ok.
+
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1') // Ok.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1', ticks=1) { // Ok.
+
+}
+
+declare(encoding='ISO-8859-1', ticks=1) // Ok.
+
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1', ticks=1) // Ok.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+/* Error if no braces are used (except for the strict_types). */
+
+declare(strict_types=1); // Error.
+
+declare(ticks=10); // Error.
+
+declare(encoding='ISO-8859-1'); // Error.
+
+declare(strict_types=1, encoding='ISO-8859-1'); // Error.
+
+/* No error if alternative syntax is used. */
+
+declare(ticks=1): // Ok.
+// Code.
+enddeclare;
+
+declare(encoding='ISO-8859-1', ticks=10): // Ok.
+// Code.
+enddeclare;
+
+declare(ticks=1): // Ok.
+    declare(ticks=1): // Ok.
+    // Code.
+    enddeclare;
+enddeclare;
+
+declare(encoding='ISO-8859-1', ticks=10): // Ok.
+    declare(ticks=1): // Ok.
+    // Code.
+    enddeclare;
+enddeclare;
+
+/* Throw errors if braces are used but also if some code is written before braces (unexpected code). */
+
+declare(ticks=1) // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1', ticks=10) // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+/* Test the required braces/alternative syntax for ticks only. */
+// phpcs:set Universal.DeclareStatements.DeclareStatementsStyle declareStyle requireBraces
+// phpcs:set Universal.DeclareStatements.DeclareStatementsStyle directiveType[] ticks
+
+declare(ticks=1) { // Ok.
+
+}
+
+declare(ticks=1) // Ok.
+
+
+{
+// Code.
+
+
+}
+
+declare(ticks=1) // Ok.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1', ticks=10); // Error.
+
+declare(encoding='ISO-8859-1', ticks=10): // Ok.
+    declare(ticks=1): // Ok.
+    // Code.
+    enddeclare;
+enddeclare;
+
+/* Error if no braces are used for ticks. */
+
+declare(ticks=100); // Error.
+
+/* No error if alternative syntax is used with ticks. */
+
+declare(ticks=1): // Ok.
+    declare(ticks=1): // Ok.
+    // Code.
+    enddeclare;
+enddeclare;
+
+/* No error for any version of encoding usage. */
+
+declare(encoding='ISO-8859-1'); // Ok.
+
+declare(encoding='ISO-8859-1', ticks=1) // Ok.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1', ticks=1) { // Ok.
+
+}
+
+declare(encoding='ISO-8859-1', ticks=1) // Ok.
+
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1') // Ok.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1') { // Ok.
+
+}
+
+declare(encoding='ISO-8859-1') // Ok.
+
+
+{
+// Code.
+
+
+}
+
+/* Throw errors if braces are used but also if some code is written before braces (unexpected code). */
+
+declare(ticks=1) // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1', ticks=10) // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+/* Test the required braces/alternative syntax for encoding only. */
+// phpcs:set Universal.DeclareStatements.DeclareStatementsStyle declareStyle requireBraces
+// phpcs:set Universal.DeclareStatements.DeclareStatementsStyle directiveType[] encoding
+
+declare(encoding='ISO-8859-1') { // Ok.
+
+}
+
+declare(encoding='ISO-8859-1') // Ok.
+
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1') // Ok.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(ticks=10, encoding='ISO-8859-1'); // Error.
+
+declare(ticks=10, encoding='ISO-8859-1'): // Ok.
+    declare(encoding='ISO-8859-1'): // Ok.
+    // Code.
+    enddeclare;
+enddeclare;
+
+/* Error if no braces are used for encoding. */
+
+declare(encoding='ISO-8859-1'); // Error.
+
+/* No error if alternative syntax is used with encoding. */
+
+declare(encoding='ISO-8859-1'): // Ok.
+    declare(encoding='ISO-8859-1'): // Ok.
+    // Code.
+    enddeclare;
+enddeclare;
+
+/* No error for any version of ticks usage. */
+
+declare(ticks=10); // Ok.
+
+declare(ticks=10, encoding='ISO-8859-1') // Ok.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(ticks=10, encoding='ISO-8859-1') { // Ok.
+
+}
+
+declare(ticks=10, encoding='ISO-8859-1') // Ok.
+
+
+{
+// Code.
+
+
+}
+
+declare(ticks=10) // Ok.
+// Comment here.
+
+{
+// Code.
+
+
+}
+
+declare(ticks=10) { // Ok.
+
+}
+
+declare(ticks=10) // Ok.
+
+
+{
+// Code.
+
+
+}
+
+/* Throw errors if braces are used but also if some code is written before braces (unexpected code). */
+
+declare(encoding='ISO-8859-1') // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+declare(ticks=10, encoding='ISO-8859-1') // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+declare(ticks=1) // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+declare(encoding='ISO-8859-1', ticks=10) // Error.
+echo 'hi!';
+
+{
+// Code.
+
+
+}
+
+declare ticks=1; // Intentional live coding error. Ignore.
diff --git a/Universal/Tests/DeclareStatements/DeclareStatementsStyleUnitTest.php b/Universal/Tests/DeclareStatements/DeclareStatementsStyleUnitTest.php
new file mode 100644
index 0000000..cceedfd
--- /dev/null
+++ b/Universal/Tests/DeclareStatements/DeclareStatementsStyleUnitTest.php
@@ -0,0 +1,78 @@
+<?php
+/**
+ * PHPCSExtra, a collection of sniffs and standards for use with PHP_CodeSniffer.
+ *
+ * @package   PHPCSExtra
+ * @copyright 2020 PHPCSExtra Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSExtra
+ */
+
+namespace PHPCSExtra\Universal\Tests\DeclareStatements;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+/**
+ * Unit test class for the DeclareStatementsStyleUnitTest sniff.
+ *
+ * @covers PHPCSExtra\Universal\Sniffs\DeclareStatements\DeclareStatementsStyleSniff
+ *
+ * @since 1.0.0
+ */
+class DeclareStatementsStyleUnitTest extends AbstractSniffUnitTest
+{
+
+    /**
+     * Returns the lines where errors should occur.
+     *
+     * @return array <int line number> => <int number of errors>
+     */
+    public function getErrorList()
+    {
+        return [
+            15  => 1,
+            19  => 1,
+            23  => 1,
+            32  => 1,
+            41  => 1,
+            45  => 1,
+            49  => 1,
+            50  => 1,
+            55  => 1,
+            56  => 1,
+            63  => 1,
+            67  => 1,
+            76  => 1,
+            85  => 1,
+            89  => 1,
+            95  => 1,
+            104 => 1,
+            185 => 1,
+            187 => 1,
+            189 => 1,
+            191 => 1,
+            217 => 1,
+            226 => 1,
+            261 => 1,
+            271 => 1,
+            331 => 1,
+            340 => 1,
+            375 => 1,
+            385 => 1,
+            445 => 1,
+            454 => 1,
+            463 => 1,
+            472 => 1,
+        ];
+    }
+
+    /**
+     * Returns the lines where warnings should occur.
+     *
+     * @return array <int line number> => <int number of warnings>
+     */
+    public function getWarningList()
+    {
+        return [];
+    }
+}