New Universal.DeclareStatements.DeclareStatementsStyle sniff

Universal/Docs/DeclareStatements/BlockModeStandard.xml

@@ -0,0 +1,60 @@
+<?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 Block Mode"
+    >
+    <standard>
+    <![CDATA[
+    Defines the block mode usage of declare directives.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Declare statement written in non-block mode.">
+        <![CDATA[
+declare(strict_types=1);
+
+declare(encoding='utf-8');
+
+declare(ticks=10):
+    // Code.
+enddeclare;
+        ]]>
+        </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(encoding='utf-8'):
+    // Code.
+    enddeclare;
+enddeclare;
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+    A declare statement for the `strict_types` directive is not allowed to be written using curly braces or with alternative syntax.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: strict_types statement not using block mode.">
+        <![CDATA[
+declare(strict_types=1);
+        ]]>
+        </code>
+        <code title="Invalid: strict_types statement using alternative syntax/curly braces.">
+        <![CDATA[
+declare(strict_types=1) <em>{</em>
+    // Code.
+<em>}</em>
+
+declare(strict_types=1) <em>:</em>
+    // Code.
+<em>enddeclare</em>;
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>

Universal/Sniffs/DeclareStatements/BlockModeSniff.php

@@ -0,0 +1,287 @@
+<?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 statements can be written in two 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 or using alternative control structure syntax
+ *    (the exception to this rule is the `strict_types` directive). This is known as block mode.
+ *
+ * There can be multiple directives inside a `declare` statement.
+ * This sniff checks the preferred mode for the `declare` statements.
+ *
+ * You can modify the sniff by changing the whether the block mode of the encoding and the ticks directives
+ * is allowed, disallowed or required. By default, the ticks directive, if written in
+ * the block mode won't trigger an error, while encoding and strict_types directives will.
+ *
+ * strict_types directive is the only one that cannot be modified because it can only be used in
+ * a non-block mode.
+ *
+ * @since 1.0.0
+ */
+class BlockModeSniff implements Sniff
+{
+
+    /**
+     * Name of the metric.
+     *
+     * @since 1.0.0
+     *
+     * @var string
+     */
+    const DECLARE_SCOPE_METRIC = 'Declare statement scope';
+
+    /**
+     * Name of the metric.
+     *
+     * @since 1.0.0
+     *
+     * @var string
+     */
+    const DECLARE_TYPE_METRIC = 'Declare directive type';
+
+    /**
+     * Whether block mode is allowed for `encoding` directives.
+     *
+     * Can be one of: 'disallow', 'allow' (no preference), or 'require'.
+     * Defaults to: 'disallow'.
+     *
+     * @since 1.0.0
+     *
+     * @var string
+     */
+    public $encodingBlockMode = 'disallow';
+
+    /**
+     * Whether block mode is allowed for `ticks` directives.
+     *
+     * Can be one of: 'disallow', 'allow' (no preference), or 'require'.
+     * Defaults to: 'allow'.
+     *
+     * @since 1.0.0
+     *
+     * @var string
+     */
+    public $ticksBlockMode = 'allow';
+
+    /**
+     * The default option for the strict_types directive.
+     *
+     * Block mode is not allowed for the `strict_types` directive.
+     * Using it in block mode will throw a PHP fatal error.
+     *
+     * @since 1.0.0
+     *
+     * @var string
+     */
+    private $strictTypesBlockMode = 'disallow';
+
+    /**
+     * Allowed declare directives.
+     *
+     * @since 1.0.0
+     *
+     * @var array
+     */
+    private $allowedDirectives = [
+        'strict_types' => true,
+        'ticks'        => true,
+        'encoding'     => true,
+    ];
+
+    /**
+     * 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();
+
+        if (isset($tokens[$stackPtr]['parenthesis_opener'], $tokens[$stackPtr]['parenthesis_closer']) === false) {
+            // Parse error or live coding, bow out.
+            return;
+        }
+
+        $openParenPtr  = $tokens[$stackPtr]['parenthesis_opener'];
+        $closeParenPtr = $tokens[$stackPtr]['parenthesis_closer'];
+
+        $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) {
+                $contentsLC = \strtolower($tokens[$i]['content']);
+                if (isset($this->allowedDirectives[$contentsLC])) {
+                    $phpcsFile->recordMetric($i, self::DECLARE_TYPE_METRIC, $contentsLC);
+                    $directiveStrings[$contentsLC] = true;
+                }
+            }
+        }
+
+        unset($i);
+
+        if (empty($directiveStrings)) {
+            // No valid directives were found, this is outside the scope of this sniff.
+            return;
+        }
+
+        $usesBlockMode = isset($tokens[$stackPtr]['scope_opener']);
+
+        if ($usesBlockMode) {
+            $phpcsFile->recordMetric($stackPtr, self::DECLARE_SCOPE_METRIC, 'Block mode');
+        } else {
+            $phpcsFile->recordMetric($stackPtr, self::DECLARE_SCOPE_METRIC, 'File mode');
+        }
+
+        // If strict types is defined using block mode, throw error.
+        if ($usesBlockMode && isset($directiveStrings['strict_types'])) {
+            $error = 'strict_types declaration must not use block mode.';
+            $code  = 'Forbidden';
+
+            if (isset($tokens[$stackPtr]['scope_closer'])) {
+                // If there is no scope closer, we cannot auto-fix.
+                $phpcsFile->addError($error, $stackPtr, $code);
+                return;
+            }
+
+            $fix = $phpcsFile->addFixableError($error, $stackPtr, $code);
+
+            if ($fix === true) {
+                $phpcsFile->fixer->beginChangeset();
+                $phpcsFile->fixer->addContent($closeParenPtr, ';');
+                $phpcsFile->fixer->replaceToken($tokens[$stackPtr]['scope_opener'], '');
+
+                // Remove potential whitespace between parenthesis closer and the brace.
+                for ($i = ($tokens[$stackPtr]['scope_opener'] - 1); $i > 0; $i--) {
+                    if ($tokens[$i]['code'] !== \T_WHITESPACE) {
+                        break;
+                    }
+
+                    $phpcsFile->fixer->replaceToken($i, '');
+                }
+
+                $phpcsFile->fixer->replaceToken($tokens[$stackPtr]['scope_closer'], '');
+                $phpcsFile->fixer->endChangeset();
+            }
+            return;
+        }
+
+        // Check if there is code between the declare statement and opening brace/alternative syntax.
+        $nextNonEmpty = $phpcsFile->findNext(Tokens::$emptyTokens, ($closeParenPtr + 1), null, true);
+        if ($tokens[$nextNonEmpty]['code'] !== \T_SEMICOLON
+            && $tokens[$nextNonEmpty]['code'] !== \T_CLOSE_TAG
+            && $tokens[$nextNonEmpty]['code'] !== \T_OPEN_CURLY_BRACKET
+            && $tokens[$nextNonEmpty]['code'] !== \T_COLON
+        ) {
+            $phpcsFile->addError(
+                'Unexpected code found after the declare statement.',
+                $stackPtr,
+                'UnexpectedCodeFound'
+            );
+            return;
+        }
+
+        // Multiple directives - if one requires block mode usage, other has to as well.
+        if (count($directiveStrings) > 1
+            && (($this->encodingBlockMode === 'disallow' && $this->ticksBlockMode !== 'disallow')
+                || ($this->ticksBlockMode === 'disallow' && $this->encodingBlockMode !== 'disallow'))
+        ) {
+            $phpcsFile->addError(
+                'Multiple directives found, but one of them is disallowing the use of block mode.',
+                $stackPtr,
+                'Forbidden' // <= Duplicate error code for different message (line 175)
+            );
+            return;
+        }
+
+        if (($this->encodingBlockMode === 'allow' || $this->encodingBlockMode === 'require')
+            && $this->ticksBlockMode === 'disallow'
+            && $usesBlockMode && isset($directiveStrings['ticks'])
+        ) {
+            $phpcsFile->addError(
+                'Block mode is not allowed for ticks directive.',
+                $stackPtr,
+                'DisallowedTicksBlockMode'
+            );
+            return;
+        }
+
+        if ($this->ticksBlockMode === 'require'
+            && !$usesBlockMode && isset($directiveStrings['ticks'])
+        ) {
+            $phpcsFile->addError(
+                'Block mode is required for ticks directive.',
+                $stackPtr,
+                'RequiredTicksBlockMode'
+            );
+            return;
+        }
+
+        if ($this->encodingBlockMode === 'disallow'
+            && ($this->ticksBlockMode === 'allow' || $this->ticksBlockMode === 'require')
+            && $usesBlockMode && isset($directiveStrings['encoding'])
+        ) {
+            $phpcsFile->addError(
+                'Block mode is not allowed for encoding directive.',
+                $stackPtr,
+                'DisallowedEncodingBlockMode'
+            );
+            return;
+        }
+
+        if ($this->encodingBlockMode === 'disallow' && $this->ticksBlockMode === 'disallow' && $usesBlockMode) {
+            $phpcsFile->addError(
+                'Block mode is not allowed for any declare directive.',
+                $stackPtr,
+                'DisallowedBlockMode'
+            );
+            return;
+        }
+
+        if ($this->encodingBlockMode === 'require'
+            && !$usesBlockMode && isset($directiveStrings['encoding'])
+        ) {
+            $phpcsFile->addError(
+                'Block mode is required for encoding directive.',
+                $stackPtr,
+                'RequiredEncodingBlockMode'
+            );
+            return;
+        }
+    }
+}