README

Php DocBlock Header Fixer

This packages contains a PHP-CS-Fixer rule to automatically fix the header regarding PHP DocBlocks for classes, interfaces, traits and enums.

Warning

This package is in early development stage and may change significantly in the future. Use it at your own risk.

Before:

<?php

class MyClass
{
    public function myMethod()
    {
        // ...
    }
}

interface MyInterface {}
trait MyTrait {}
enum MyEnum {}

After:

<?php
/**
 * MyClass.
 *
 * @author Your Name <your@email.org>
 */
class MyClass
{
    // ...
}

🔥 Installation

composer require --dev konradmichalik/php-doc-block-header-fixer

⚡ Usage

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
// ...
return (new PhpCsFixer\Config())
    // ...
    ->registerCustomFixers([
        new KonradMichalik\PhpDocBlockHeaderFixer\Rules\DocBlockHeaderFixer()
    ])
    ->setRules([
        'KonradMichalik/docblock_header_comment' => [
            'annotations' => [
                'author' => 'Konrad Michalik <hej@konradmichalik.dev>',
                'license' => 'GPL-3.0-or-later',
            ],
            'preserve_existing' => true,
            'separate' => 'none',
            'add_structure_name' => true,
        ],
    ])
;

Alternatively, you can use a object-oriented configuration:

<?php
// ...
return (new PhpCsFixer\Config())
    // ...
    ->registerCustomFixers([
        new KonradMichalik\PhpDocBlockHeaderFixer\Rules\DocBlockHeaderFixer()
    ])
    ->setRules([
        KonradMichalik\PhpDocBlockHeaderFixer\Generators\DocBlockHeader::create(
            [
                'author' => 'Konrad Michalik <hej@konradmichalik.dev>',
                'license' => 'GPL-3.0-or-later',
            ],
            preserveExisting: true,
            separate: \KonradMichalik\PhpDocBlockHeaderFixer\Enum\Separate::None,
            addStructureName: true
        )->__toArray()
    ])
;

⚙️ 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.

⭐ License

This project is licensed under GNU General Public License 3.0 (or later).

konradmichalik / php-doc-block-header-fixer

Maintainers

Details