✨ Check phpDoc tag spacing

Author: VincentLanglet

SymfonyCustom/Sniffs/WhiteSpace/DocCommentTagSpacingSniff.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace SymfonyCustom\Sniffs\WhiteSpace;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+/**
+ * Checks that there are not 2 empty lines following each other.
+ */
+class DocCommentTagSpacingSniff implements Sniff
+{
+    /**
+     * Returns an array of tokens this test wants to listen for.
+     *
+     * @return array
+     */
+    public function register()
+    {
+        return array(
+            T_DOC_COMMENT_TAG
+        );
+    }
+
+    /**
+     * Processes this test, when one of its tokens is encountered.
+     *
+     * @param 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 - 1)]) || T_DOC_COMMENT_WHITESPACE !== $tokens[($stackPtr - 1)]['code']) {
+            $error = 'There should be a space before a doc comment tag "%s"';
+            $fix = $phpcsFile->addFixableError(
+                $error,
+                ($stackPtr - 1),
+                'DocCommentTagSpacing',
+                array($tokens[$stackPtr]['content'])
+            );
+
+            if (true === $fix) {
+                $phpcsFile->fixer->addContentBefore($stackPtr, ' ');
+            }
+        } elseif (1 !== $tokens[($stackPtr - 1)]['length']) {
+            $error = 'There should be only one space before a doc comment tag "%s"';
+            $fix = $phpcsFile->addFixableError(
+                $error,
+                ($stackPtr + 1),
+                'DocCommentTagSpacing',
+                array($tokens[$stackPtr]['content'])
+            );
+
+            if (true === $fix) {
+                $phpcsFile->fixer->replaceToken($stackPtr - 1, ' ');
+            }
+        }
+
+        // No need to check for space after a doc comment tag
+        if (isset($tokens[($stackPtr + 1)])
+            && T_DOC_COMMENT_WHITESPACE === $tokens[($stackPtr + 1)]['code']
+            && 1 !== $tokens[($stackPtr + 1)]['length']
+        ) {
+            $error = 'There should be only one space after a doc comment tag "%s"';
+            $fix = $phpcsFile->addFixableError(
+                $error,
+                ($stackPtr + 1),
+                'DocCommentTagSpacing',
+                array($tokens[$stackPtr]['content'])
+            );
+
+            if (true === $fix) {
+                $phpcsFile->fixer->replaceToken($stackPtr + 1, ' ');
+            }
+        }
+    }
+}

SymfonyCustom/Tests/WhiteSpace/DocCommentTagSpacingUnitTest.inc

@@ -0,0 +1,33 @@
+<?php
+
+class DocCommentTagSpacingUnitTest
+{
+    /**
+     * Short description of the member variable.
+     *
+     * Long description of member variable. Can span over multiple
+     * lines and can have multiple paragraphs.
+     *
+     *@var array
+     *
+     *  @see otherFunctions()
+     * @see       anotherFunctions()
+     */
+     public $variableName = array();
+
+    /**
+     * T_VARIABLE check, var in string and in function.
+     *
+     *@param integer $var1 First variable.
+     * @param  integer $var2 Second variable.
+     *
+     *  @return integer
+     */
+    protected function checkFunction($var1, $var2)
+    {
+        /**@var int $var3 */
+        $var3 = $var1 + $var2;
+
+        return $var3;
+    }
+}

SymfonyCustom/Tests/WhiteSpace/DocCommentTagSpacingUnitTest.inc.fixed

@@ -0,0 +1,33 @@
+<?php
+
+class DocCommentTagSpacingUnitTest
+{
+    /**
+     * Short description of the member variable.
+     *
+     * Long description of member variable. Can span over multiple
+     * lines and can have multiple paragraphs.
+     *
+     * @var array
+     *
+     * @see otherFunctions()
+     * @see anotherFunctions()
+     */
+     public $variableName = array();
+
+    /**
+     * T_VARIABLE check, var in string and in function.
+     *
+     * @param integer $var1 First variable.
+     * @param integer $var2 Second variable.
+     *
+     * @return integer
+     */
+    protected function checkFunction($var1, $var2)
+    {
+        /** @var int $var3 */
+        $var3 = $var1 + $var2;
+
+        return $var3;
+    }
+}

SymfonyCustom/Tests/WhiteSpace/DocCommentTagSpacingUnitTest.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace SymfonyCustom\Tests\WhiteSpace;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+/**
+ * Unit test class for the CloseBracketSpacing sniff.
+ *
+ * @group SymfonyCustom
+ */
+class DocCommentTagSpacingUnitTest extends AbstractSniffUnitTest
+{
+    /**
+     * Returns the lines where errors should occur.
+     *
+     * The key of the array should represent the line number and the value
+     * should represent the number of errors that should occur on that line.
+     *
+     * @return array<int, int>
+     */
+    public function getErrorList()
+    {
+        return array(
+            11 => 1,
+            13 => 1,
+            14 => 1,
+            21 => 1,
+            22 => 1,
+            24 => 1,
+            28 => 1,
+        );
+    }
+
+    /**
+     * Returns the lines where warnings should occur.
+     *
+     * The key of the array should represent the line number and the value
+     * should represent the number of warnings that should occur on that line.
+     *
+     * @return array(int => int)
+     */
+    protected function getWarningList()
+    {
+        return array();
+    }
+}