feature #4880 HeredocIndentationFixer - config option for indentation…

… level (gharlan)

This PR was merged into the 2.17-dev branch.

Discussion
----------

HeredocIndentationFixer - config option for indentation level

We discussed the best indentation level for the HeredocIndentationFixer [here](#3697 (comment)) and [here](#3915).

But now since I'm actually using it, I changed my mind.
I would like to write code like this:

```php
    public function foo()
    {
        return $this->createQuery(<<<'DQL'
            SELECT foo
            FROM App\Entity\Foo foo
            WHERE ...
        DQL)->getResult();
    }
```

and NOT:

```php
    public function foo()
    {
        return $this->createQuery(<<<'DQL'
            SELECT foo
            FROM App\Entity\Foo foo
            WHERE ...
            DQL)->getResult();
    }
```

So I suggest to add a config option `indentation` with possible values `start_plus_one` (default; same as current behavior) and `same_as_start` (new behavior). (Ideas for better names?)

The fixer will remain non-risky, so it does not change the actual string result.
This input:

```php
    $dql = <<<'DQL'
SELECT foo
FROM App\Entity\Foo foo
DQL;
```

will be changed with the new behavior (`same_as_start`) to:

```php
    $dql = <<<'DQL'
    SELECT foo
    FROM App\Entity\Foo foo
    DQL;
```

Adding one more indentation level inside string content is not part of this fixer (as it would be risky).

Commits
-------

b03554d HeredocIndentationFixer - config option for indentation level

README.rst

@@ -814,6 +814,12 @@ Choose from the list of available rules:
 
   Heredoc/nowdoc content must be properly indented. Requires PHP >= 7.3.
 
+  Configuration options:
+
+  - ``indentation`` (``'same_as_start'``, ``'start_plus_one'``): whether the indentation
+    should be the same as in the start token line or one level more;
+    defaults to ``'start_plus_one'``
+
 * **heredoc_to_nowdoc** [@PhpCsFixer]
 
   Convert ``heredoc`` to ``nowdoc`` where possible.

src/Fixer/Whitespace/HeredocIndentationFixer.php

@@ -13,7 +13,10 @@
 namespace PhpCsFixer\Fixer\Whitespace;
 
 use PhpCsFixer\AbstractFixer;
+use PhpCsFixer\Fixer\ConfigurationDefinitionFixerInterface;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
+use PhpCsFixer\FixerConfiguration\FixerConfigurationResolver;
+use PhpCsFixer\FixerConfiguration\FixerOptionBuilder;
 use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\FixerDefinition\VersionSpecification;
 use PhpCsFixer\FixerDefinition\VersionSpecificCodeSample;
@@ -24,7 +27,7 @@
 /**
  * @author Gregor Harlan
  */
-final class HeredocIndentationFixer extends AbstractFixer implements WhitespacesAwareFixerInterface
+final class HeredocIndentationFixer extends AbstractFixer implements ConfigurationDefinitionFixerInterface, WhitespacesAwareFixerInterface
 {
     /**
      * {@inheritdoc}
@@ -58,6 +61,19 @@ public function getDefinition()
                     ,
                     new VersionSpecification(70300)
                 ),
+                new VersionSpecificCodeSample(
+                    <<<'SAMPLE'
+<?php
+    $a = <<<'EOD'
+abc
+    def
+EOD;
+
+SAMPLE
+                    ,
+                    new VersionSpecification(70300),
+                    ['indentation' => 'same_as_start']
+                ),
             ]
         );
     }
@@ -70,6 +86,19 @@ public function isCandidate(Tokens $tokens)
         return \PHP_VERSION_ID >= 70300 && $tokens->isTokenKindFound(T_START_HEREDOC);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    protected function createConfigurationDefinition()
+    {
+        return new FixerConfigurationResolver([
+            (new FixerOptionBuilder('indentation', 'Whether the indentation should be the same as in the start token line or one level more.'))
+                ->setAllowedValues(['start_plus_one', 'same_as_start'])
+                ->setDefault('start_plus_one')
+                ->getOption(),
+        ]);
+    }
+
     protected function applyFix(\SplFileInfo $file, Tokens $tokens)
     {
         for ($index = \count($tokens) - 1; 0 <= $index; --$index) {
@@ -90,7 +119,11 @@ protected function applyFix(\SplFileInfo $file, Tokens $tokens)
      */
     private function fixIndentation(Tokens $tokens, $start, $end)
     {
-        $indent = $this->getIndentAt($tokens, $start).$this->whitespacesConfig->getIndent();
+        $indent = $this->getIndentAt($tokens, $start);
+
+        if ('start_plus_one' === $this->configuration['indentation']) {
+            $indent .= $this->whitespacesConfig->getIndent();
+        }
 
         Preg::match('/^\h*/', $tokens[$end]->getContent(), $matches);
         $currentIndent = $matches[0];

tests/Fixer/Whitespace/HeredocIndentationFixerTest.php

@@ -48,8 +48,9 @@ public function testDoNotFix()
      * @dataProvider provideFixCases
      * @requires PHP 7.3
      */
-    public function testFix($expected, $input = null)
+    public function testFix($expected, $input = null, array $config = [])
     {
+        $this->fixer->configure($config);
         $this->doTest($expected, $input);
     }
 
@@ -258,6 +259,52 @@ public function provideFixCases()
 INPUT
                 ,
             ],
+            [
+                <<<'EXPECTED'
+<?php
+    foo(<<<EOD
+    abc
+
+        def
+    EOD
+    );
+EXPECTED
+                ,
+                <<<'INPUT'
+<?php
+    foo(<<<EOD
+abc
+
+    def
+EOD
+    );
+INPUT
+                ,
+                ['indentation' => 'same_as_start'],
+            ],
+            [
+                <<<'EXPECTED'
+<?php
+    foo(<<<EOD
+    abc
+
+        def
+    EOD
+    );
+EXPECTED
+                ,
+                <<<'INPUT'
+<?php
+    foo(<<<EOD
+        abc
+
+            def
+        EOD
+    );
+INPUT
+                ,
+                ['indentation' => 'same_as_start'],
+            ],
         ];
     }