Merge pull request #6 from jackd248/ensure-spacing

feat: ensure spacing

Author: jackd248

README.md

@@ -110,6 +110,14 @@ return (new PhpCsFixer\Config())
 ;
 ```
 
+## ⚙️ Configuration
+
+- `annotations` (array): DocBlock annotations to add to classes
+- `preserve_existing` (boolean, default: true): Keep existing DocBlock annotations
+- `separate` (string, default: 'none'): Add blank lines ('top', 'bottom', 'both', 'none')
+- `add_structure_name` (boolean, default: false): Add class name as first line in DocBlock
+- `ensure_spacing` (boolean, default: true): Ensure proper spacing after DocBlocks to prevent conflicts with PHP-CS-Fixer rules
+
 ## 🧑‍💻 Contributing
 
 Please have a look at [`CONTRIBUTING.md`](CONTRIBUTING.md).

src/Rules/DocBlockHeaderFixer.php

@@ -61,6 +61,13 @@ public function getName(): string
         return 'KonradMichalik/docblock_header_comment';
     }
 
+    public function getPriority(): int
+    {
+        // Run before single_line_after_imports (0) and no_extra_blank_lines (0)
+        // Higher priority values run first
+        return 1;
+    }
+
     public function isCandidate(Tokens $tokens): bool
     {
         return $tokens->isTokenKindFound(T_CLASS)
@@ -88,6 +95,10 @@ public function getConfigurationDefinition(): FixerConfigurationResolverInterfac
                 ->setAllowedTypes(['bool'])
                 ->setDefault(false)
                 ->getOption(),
+            (new FixerOptionBuilder('ensure_spacing', 'Ensure proper spacing after DocBlock to prevent conflicts with PHP-CS-Fixer rules'))
+                ->setAllowedTypes(['bool'])
+                ->setDefault(true)
+                ->getOption(),
         ]);
     }
 
@@ -189,6 +200,12 @@ private function mergeWithExistingDocBlock(Tokens $tokens, int $docBlockIndex, a
 
         $newDocBlock = $this->buildDocBlock($mergedAnnotations, $structureName);
         $tokens[$docBlockIndex] = new Token([T_DOC_COMMENT, $newDocBlock]);
+
+        // Ensure there's proper spacing after existing DocBlock
+        $ensureSpacing = $this->resolvedConfiguration['ensure_spacing'] ?? true;
+        if ($ensureSpacing) {
+            $this->ensureProperSpacingAfterDocBlock($tokens, $docBlockIndex);
+        }
     }
 
     /**
@@ -198,6 +215,12 @@ private function replaceDocBlock(Tokens $tokens, int $docBlockIndex, array $anno
     {
         $newDocBlock = $this->buildDocBlock($annotations, $structureName);
         $tokens[$docBlockIndex] = new Token([T_DOC_COMMENT, $newDocBlock]);
+
+        // Ensure there's proper spacing after replaced DocBlock
+        $ensureSpacing = $this->resolvedConfiguration['ensure_spacing'] ?? true;
+        if ($ensureSpacing) {
+            $this->ensureProperSpacingAfterDocBlock($tokens, $docBlockIndex);
+        }
     }
 
     /**
@@ -219,8 +242,14 @@ private function insertNewDocBlock(Tokens $tokens, int $structureIndex, array $a
         $docBlock = $this->buildDocBlock($annotations, $structureName);
         $tokensToInsert[] = new Token([T_DOC_COMMENT, $docBlock]);
 
-        // For compatibility with no_blank_lines_after_phpdoc, only add bottom separation when 'separate' is not 'none'
-        // This prevents conflicts with PHP-CS-Fixer rules that manage DocBlock spacing
+        // Add a newline after the DocBlock if ensure_spacing is enabled (default)
+        // This prevents conflicts with single_line_after_imports and no_extra_blank_lines rules
+        $ensureSpacing = $this->resolvedConfiguration['ensure_spacing'] ?? true;
+        if ($ensureSpacing) {
+            $tokensToInsert[] = new Token([T_WHITESPACE, "\n"]);
+        }
+
+        // Add additional separation if configured
         if (in_array($separate, ['bottom', 'both'], true)) {
             // Check if there's already whitespace after the structure declaration
             $nextToken = $tokens[$structureIndex] ?? null;
@@ -327,4 +356,23 @@ private function buildDocBlock(array $annotations, string $structureName): strin
 
         return $docBlock;
     }
+
+    /**
+     * Ensures proper spacing after a DocBlock to prevent conflicts with PHP-CS-Fixer rules.
+     */
+    private function ensureProperSpacingAfterDocBlock(Tokens $tokens, int $docBlockIndex): void
+    {
+        $nextIndex = $docBlockIndex + 1;
+
+        // Check if the next token exists and is not already a newline
+        if ($nextIndex < $tokens->count()) {
+            $nextToken = $tokens[$nextIndex];
+
+            // If the next token is not whitespace or doesn't contain a newline, add one
+            if (!$nextToken->isWhitespace() || !str_contains($nextToken->getContent(), "\n")) {
+                // Insert a newline token after the DocBlock
+                $tokens->insertAt($nextIndex, [new Token([T_WHITESPACE, "\n"])]);
+            }
+        }
+    }
 }

tests/src/Rules/DocBlockHeaderFixerTest.php

@@ -170,13 +170,14 @@ public function testConfigurationDefinition(): void
         $configDefinition = $this->fixer->getConfigurationDefinition();
         $options = $configDefinition->getOptions();
 
-        self::assertCount(4, $options);
+        self::assertCount(5, $options);
 
         $optionNames = array_map(fn ($option) => $option->getName(), $options);
         self::assertContains('annotations', $optionNames);
         self::assertContains('preserve_existing', $optionNames);
         self::assertContains('separate', $optionNames);
         self::assertContains('add_structure_name', $optionNames);
+        self::assertContains('ensure_spacing', $optionNames);
     }
 
     public function testParseExistingAnnotations(): void
@@ -237,6 +238,7 @@ public function testApplyFixAddsDocBlockToClass(): void
         $this->fixer->configure([
             'annotations' => ['author' => 'John Doe'],
             'separate' => 'none',
+            'ensure_spacing' => false,
         ]);
         $method->invoke($this->fixer, $file, $tokens);
 
@@ -255,6 +257,7 @@ public function testApplyFixHandlesMultipleClasses(): void
         $this->fixer->configure([
             'annotations' => ['author' => 'John Doe'],
             'separate' => 'none',
+            'ensure_spacing' => false,
         ]);
         $method->invoke($this->fixer, $file, $tokens);
 
@@ -270,7 +273,7 @@ public function testProcessClassDocBlockWithNewDocBlock(): void
 
         $method = new ReflectionMethod($this->fixer, 'processStructureDocBlock');
 
-        $this->fixer->configure(['separate' => 'none']);
+        $this->fixer->configure(['separate' => 'none', 'ensure_spacing' => false]);
         $method->invoke($this->fixer, $tokens, 1, $annotations, 'Foo');
 
         $expected = "<?php /**\n * @author John Doe\n */class Foo {}";
@@ -379,7 +382,7 @@ public function testInsertNewDocBlockWithSeparateNone(): void
 
         $method = new ReflectionMethod($this->fixer, 'insertNewDocBlock');
 
-        $this->fixer->configure(['separate' => 'none']);
+        $this->fixer->configure(['separate' => 'none', 'ensure_spacing' => false]);
         $method->invoke($this->fixer, $tokens, 1, $annotations, 'Foo');
 
         $expected = "<?php /**\n * @author John Doe\n */class Foo {}";
@@ -702,6 +705,7 @@ public function testApplyFixAddsDocBlockToInterface(): void
         $this->fixer->configure([
             'annotations' => ['author' => 'John Doe'],
             'separate' => 'none',
+            'ensure_spacing' => false,
         ]);
         $method->invoke($this->fixer, $file, $tokens);
 
@@ -720,6 +724,7 @@ public function testApplyFixAddsDocBlockToTrait(): void
         $this->fixer->configure([
             'annotations' => ['author' => 'Jane Doe'],
             'separate' => 'none',
+            'ensure_spacing' => false,
         ]);
         $method->invoke($this->fixer, $file, $tokens);
 
@@ -738,6 +743,7 @@ public function testApplyFixAddsDocBlockToEnum(): void
         $this->fixer->configure([
             'annotations' => ['license' => 'MIT'],
             'separate' => 'none',
+            'ensure_spacing' => false,
         ]);
         $method->invoke($this->fixer, $file, $tokens);
 
@@ -757,6 +763,7 @@ public function testApplyFixWithClassNameEnabled(): void
             'annotations' => ['author' => 'John Doe'],
             'add_structure_name' => true,
             'separate' => 'none',
+            'ensure_spacing' => false,
         ]);
         $method->invoke($this->fixer, $file, $tokens);
 
@@ -776,6 +783,7 @@ public function testApplyFixWithMultipleClassesAndClassName(): void
             'annotations' => ['author' => 'John Doe'],
             'add_structure_name' => true,
             'separate' => 'none',
+            'ensure_spacing' => false,
         ]);
         $method->invoke($this->fixer, $file, $tokens);
 
@@ -830,6 +838,7 @@ public function testInsertNewDocBlockWithClassNameAndSeparateNone(): void
         $this->fixer->configure([
             'add_structure_name' => true,
             'separate' => 'none',
+            'ensure_spacing' => false,
         ]);
         $method->invoke($this->fixer, $tokens, 1, $annotations, 'TestClass');