feature #4571 BlankLineBeforeStatementFixer - can now add blank lines…

… before doc-comments (addiks, SpacePossum)

This PR was merged into the master branch.

Discussion
----------

BlankLineBeforeStatementFixer - can now add blank lines before doc-comments

This PR adds the "doccomment" token to the blank-line-before-statement-fixer.

Now the php-cs-fixer can automatically turn this:

```php
/** @var int $foo */
$foo = 123;
/** @var int $bar */
$bar = 456;
/** @var int $baz */
$baz = 789;
```

... into this:

```php
/** @var int $foo */
$foo = 123;

/** @var int $bar */
$bar = 456;

/** @var int $baz */
$baz = 789;
```

Commits
-------

d5c6851 Update project CS
ef752ba BlankLineBeforeStatementFixer - add "phpdoc"

.gitattributes

@@ -17,4 +17,5 @@
 *.php   text whitespace=blank-at-eol,blank-at-eof,space-before-tab,tab-in-indent,tabwidth=4 diff=php
 *.rst   text whitespace=blank-at-eol,blank-at-eof
 *.yml   text whitespace=blank-at-eol,blank-at-eof,space-before-tab,tab-in-indent,tabwidth=4
+*.png   binary eol=unset
 /tests/Fixtures/**/* -text -filter

doc/list.rst

@@ -106,7 +106,7 @@ List of Available Rules
 
    - | ``statements``
      | List of statements which must be preceded by an empty line.
-     | Allowed values: a subset of ``['break', 'case', 'continue', 'declare', 'default', 'do', 'exit', 'for', 'foreach', 'goto', 'if', 'include', 'include_once', 'require', 'require_once', 'return', 'switch', 'throw', 'try', 'while', 'yield', 'yield_from']``
+     | Allowed values: a subset of ``['break', 'case', 'continue', 'declare', 'default', 'phpdoc', 'do', 'exit', 'for', 'foreach', 'goto', 'if', 'include', 'include_once', 'require', 'require_once', 'return', 'switch', 'throw', 'try', 'while', 'yield', 'yield_from']``
      | Default value: ``['break', 'continue', 'declare', 'return', 'throw', 'try']``
 
 

doc/ruleSets/PhpCsFixer.rst

@@ -12,7 +12,7 @@ Rules
 - `array_indentation <./../rules/whitespace/array_indentation.rst>`_
 - `blank_line_before_statement <./../rules/whitespace/blank_line_before_statement.rst>`_
   config:
-  ``['statements' => ['break', 'case', 'continue', 'declare', 'default', 'exit', 'goto', 'include', 'include_once', 'require', 'require_once', 'return', 'switch', 'throw', 'try']]``
+  ``['statements' => ['break', 'case', 'continue', 'declare', 'default', 'exit', 'goto', 'include', 'include_once', 'phpdoc', 'require', 'require_once', 'return', 'switch', 'throw', 'try']]``
 - `combine_consecutive_issets <./../rules/language_construct/combine_consecutive_issets.rst>`_
 - `combine_consecutive_unsets <./../rules/language_construct/combine_consecutive_unsets.rst>`_
 - `empty_loop_body <./../rules/control_structure/empty_loop_body.rst>`_

doc/rules/whitespace/blank_line_before_statement.rst

@@ -12,7 +12,7 @@ Configuration
 
 List of statements which must be preceded by an empty line.
 
-Allowed values: a subset of ``['break', 'case', 'continue', 'declare', 'default', 'do', 'exit', 'for', 'foreach', 'goto', 'if', 'include', 'include_once', 'require', 'require_once', 'return', 'switch', 'throw', 'try', 'while', 'yield', 'yield_from']``
+Allowed values: a subset of ``['break', 'case', 'continue', 'declare', 'default', 'phpdoc', 'do', 'exit', 'for', 'foreach', 'goto', 'if', 'include', 'include_once', 'require', 'require_once', 'return', 'switch', 'throw', 'try', 'while', 'yield', 'yield_from']``
 
 Default value: ``['break', 'continue', 'declare', 'return', 'throw', 'try']``
 
@@ -235,7 +235,7 @@ The rule is part of the following rule sets:
 @PhpCsFixer
   Using the `@PhpCsFixer <./../../ruleSets/PhpCsFixer.rst>`_ rule set will enable the ``blank_line_before_statement`` rule with the config below:
 
-  ``['statements' => ['break', 'case', 'continue', 'declare', 'default', 'exit', 'goto', 'include', 'include_once', 'require', 'require_once', 'return', 'switch', 'throw', 'try']]``
+  ``['statements' => ['break', 'case', 'continue', 'declare', 'default', 'exit', 'goto', 'include', 'include_once', 'phpdoc', 'require', 'require_once', 'return', 'switch', 'throw', 'try']]``
 
 @Symfony
   Using the `@Symfony <./../../ruleSets/Symfony.rst>`_ rule set will enable the ``blank_line_before_statement`` rule with the config below:

src/Console/Report/FixReport/JunitReporter.php

@@ -43,6 +43,7 @@ public function generate(ReportSummary $reportSummary): string
 
         $dom = new \DOMDocument('1.0', 'UTF-8');
         $testsuites = $dom->appendChild($dom->createElement('testsuites'));
+
         /** @var \DomElement $testsuite */
         $testsuite = $testsuites->appendChild($dom->createElement('testsuite'));
         $testsuite->setAttribute('name', 'PHP CS Fixer');

src/Fixer/PhpTag/BlankLineAfterOpeningTagFixer.php

@@ -70,6 +70,7 @@ protected function applyFix(\SplFileInfo $file, Tokens $tokens): void
         }
 
         $newlineFound = false;
+
         /** @var Token $token */
         foreach ($tokens as $token) {
             if ($token->isWhitespace() && str_contains($token->getContent(), "\n")) {

src/Fixer/Whitespace/BlankLineBeforeStatementFixer.php

@@ -43,6 +43,7 @@ final class BlankLineBeforeStatementFixer extends AbstractFixer implements Confi
         'continue' => T_CONTINUE,
         'declare' => T_DECLARE,
         'default' => T_DEFAULT,
+        'phpdoc' => T_DOC_COMMENT,
         'do' => T_DO,
         'exit' => T_EXIT,
         'for' => T_FOR,

src/RuleSet/Sets/PhpCsFixerSet.php

@@ -38,6 +38,7 @@ public function getRules(): array
                     'goto',
                     'include',
                     'include_once',
+                    'phpdoc',
                     'require',
                     'require_once',
                     'return',

tests/Fixer/Alias/NoAliasFunctionsFixerTest.php

@@ -255,6 +255,7 @@ public function provideFix81Cases(): \Generator
     private function provideAllCases(): \Generator
     {
         $reflectionConstant = new \ReflectionClassConstant(\PhpCsFixer\Fixer\Alias\NoAliasFunctionsFixer::class, 'SETS');
+
         /** @var array<string, string[]> $allAliases */
         $allAliases = $reflectionConstant->getValue();
 

tests/Fixer/Whitespace/BlankLineBeforeStatementFixerTest.php

@@ -1491,6 +1491,56 @@ public function label(): string {
         return "label";
     }
 }
+',
+        ];
+    }
+
+    /**
+     * @dataProvider provideFixWithDocCommentCases
+     */
+    public function testFixWithDocCommentCases(string $expected, string $input = null): void
+    {
+        $this->fixer->configure([
+            'statements' => ['phpdoc'],
+        ]);
+
+        $this->doTest($expected, $input);
+    }
+
+    public function provideFixWithDocCommentCases(): iterable
+    {
+        yield [
+            '<?php
+/** @var int $foo */
+$foo = 123;
+
+/** @var float $bar */
+$bar = 45.6;
+
+/** @var string */
+$baz = "789";
+',
+            '<?php
+/** @var int $foo */
+$foo = 123;
+/** @var float $bar */
+$bar = 45.6;
+/** @var string */
+$baz = "789";
+',
+        ];
+
+        yield [
+            '<?php
+/* header */
+
+/**
+ * Class description
+ */
+class Foo {
+    /** test */
+    public function bar() {}
+}
 ',
         ];
     }

tests/Tokenizer/TokensTest.php

@@ -464,6 +464,7 @@ public function bar()
 }
 PHP;
         $tokens = Tokens::fromCode($source);
+
         /** @var Token[] $found */
         $found = $tokens->findGivenKind(T_CLASS);
         static::assertCount(1, $found);