From 62c1647348d14d3878d390c6779b7e9cab110f52 Mon Sep 17 00:00:00 2001 From: Konrad Michalik Date: Thu, 4 Sep 2025 20:15:38 +0200 Subject: [PATCH 1/3] refactor(!): remove 'package' annotation from DocBlock examples and update package description in composer.json --- .gitignore | 1 + README.md | 6 +++--- composer.json | 2 +- tests/src/Generators/DocBlockHeaderTest.php | 1 - tests/src/Rules/DocBlockHeaderFixerTest.php | 3 +-- 5 files changed, 6 insertions(+), 7 deletions(-) diff --git a/.gitignore b/.gitignore index cb72a0d..e1d3265 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ /.php-cs-fixer.cache /.phpunit.result.cache /.build +/coverage-report /php-cs-fixer.xml /phpstan.xml /site diff --git a/README.md b/README.md index bf88e15..5cd8d9e 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,6 @@ class MyClass * MyClass. * * @author Your Name - * @package MyPackage */ class MyClass { @@ -58,6 +57,9 @@ composer require --dev konradmichalik/php-doc-block-header-fixer Add the PHP-CS-Fixer rule in your `.php-cs-fixer.php` file: +> [!NOTE] +> This fixer is compatible with standard PHP-CS-Fixer rules. It avoids adding annotations that conflict with rules like `phpdoc_no_package` and follows spacing conventions compatible with `phpdoc_separation`. + ```php [ 'author' => 'Konrad Michalik ', 'license' => 'GPL-3.0-or-later', - 'package' => 'PhpDocBlockHeaderFixer', ], 'preserve_existing' => true, 'separate' => 'none', @@ -96,7 +97,6 @@ return (new PhpCsFixer\Config()) [ 'author' => 'Konrad Michalik ', 'license' => 'GPL-3.0-or-later', - 'package' => 'PhpDocBlockHeaderFixer', ], preserveExisting: true, separate: \KonradMichalik\PhpDocBlockHeaderFixer\Enum\Separate::None, diff --git a/composer.json b/composer.json index 66b095d..b5036ac 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "konradmichalik/php-doc-block-header-fixer", - "description": "", + "description": "This packages contains a PHP-CS-Fixer rule to automatically fix the class header regarding PHP DocBlocks.", "license": "GPL-3.0-or-later", "type": "library", "authors": [ diff --git a/tests/src/Generators/DocBlockHeaderTest.php b/tests/src/Generators/DocBlockHeaderTest.php index a0e1156..241f5d2 100644 --- a/tests/src/Generators/DocBlockHeaderTest.php +++ b/tests/src/Generators/DocBlockHeaderTest.php @@ -125,7 +125,6 @@ public function testValidateAnnotationsWithValidKeys(): void 'license' => 'MIT', 'version' => '1.0.0', 'since' => '1.0.0', - 'package' => 'MyPackage', 'subpackage' => 'SubPackage', 'see' => 'https://example.com', 'link' => 'https://example.com', diff --git a/tests/src/Rules/DocBlockHeaderFixerTest.php b/tests/src/Rules/DocBlockHeaderFixerTest.php index 13788ff..ccc56ff 100644 --- a/tests/src/Rules/DocBlockHeaderFixerTest.php +++ b/tests/src/Rules/DocBlockHeaderFixerTest.php @@ -97,10 +97,9 @@ public function testBuildDocBlockWithMultipleAnnotations(): void $result = $method->invoke($this->fixer, [ 'author' => 'John Doe ', 'license' => 'MIT', - 'package' => 'MyPackage', ], ''); - $expected = "/**\n * @author John Doe \n * @license MIT\n * @package MyPackage\n */"; + $expected = "/**\n * @author John Doe \n * @license MIT\n */"; self::assertSame($expected, $result); } From fd318820853af2bc6f401c5b4847dcc0a27d66b4 Mon Sep 17 00:00:00 2001 From: Konrad Michalik Date: Thu, 4 Sep 2025 20:28:30 +0200 Subject: [PATCH 2/3] fix: update default value for 'separate' option to 'none' and improve DocBlock spacing compatibility --- src/Rules/DocBlockHeaderFixer.php | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/src/Rules/DocBlockHeaderFixer.php b/src/Rules/DocBlockHeaderFixer.php index f82faf0..5e806a6 100644 --- a/src/Rules/DocBlockHeaderFixer.php +++ b/src/Rules/DocBlockHeaderFixer.php @@ -79,7 +79,7 @@ public function getConfigurationDefinition(): FixerConfigurationResolverInterfac ->getOption(), (new FixerOptionBuilder('separate', 'Separate the comment')) ->setAllowedValues(Separate::getList()) - ->setDefault(Separate::Both->value) + ->setDefault(Separate::None->value) ->getOption(), (new FixerOptionBuilder('add_class_name', 'Add class name before annotations')) ->setAllowedTypes(['bool']) @@ -202,7 +202,7 @@ private function replaceDocBlock(Tokens $tokens, int $docBlockIndex, array $anno */ private function insertNewDocBlock(Tokens $tokens, int $classIndex, array $annotations, string $className): void { - $separate = $this->resolvedConfiguration['separate'] ?? 'both'; + $separate = $this->resolvedConfiguration['separate'] ?? 'none'; $insertIndex = $this->findInsertPosition($tokens, $classIndex); $tokensToInsert = []; @@ -216,9 +216,14 @@ private function insertNewDocBlock(Tokens $tokens, int $classIndex, array $annot $docBlock = $this->buildDocBlock($annotations, $className); $tokensToInsert[] = new Token([T_DOC_COMMENT, $docBlock]); - // Add separation after comment if needed + // 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 if (in_array($separate, ['bottom', 'both'], true)) { - $tokensToInsert[] = new Token([T_WHITESPACE, "\n"]); + // Check if there's already whitespace after the class declaration + $nextToken = $tokens[$classIndex] ?? null; + if (null !== $nextToken && !$nextToken->isWhitespace()) { + $tokensToInsert[] = new Token([T_WHITESPACE, "\n"]); + } } $tokens->insertAt($insertIndex, $tokensToInsert); @@ -296,7 +301,7 @@ private function buildDocBlock(array $annotations, string $className): string if ($addClassName && !empty($className)) { $docBlock .= " * {$className}.\n"; - // Add empty line after class name if there are annotations + // Add empty line after class name if there are annotations - compatible with phpdoc_separation if (!empty($annotations)) { $docBlock .= " *\n"; } From a745d5efc743ebd8a7af7ab22d0c1db242359786 Mon Sep 17 00:00:00 2001 From: Konrad Michalik Date: Thu, 4 Sep 2025 20:29:25 +0200 Subject: [PATCH 3/3] fix: correct grammatical error in package description in composer.json --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index b5036ac..87943be 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "konradmichalik/php-doc-block-header-fixer", - "description": "This packages contains a PHP-CS-Fixer rule to automatically fix the class header regarding PHP DocBlocks.", + "description": "This package contains a PHP-CS-Fixer rule to automatically fix the class header regarding PHP DocBlocks.", "license": "GPL-3.0-or-later", "type": "library", "authors": [