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.

Before:

<?php

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

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

After:

<?php
/**
 * MyClass.
 *
 * @author Your Name <your@email.org>
 * @license GPL-3.0-or-later
 */
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()
    ])
;

Or even simpler, automatically read all authors and license from your composer.json:

<?php
// ...
return (new PhpCsFixer\Config())
    // ...
    ->registerCustomFixers([
        new KonradMichalik\PhpDocBlockHeaderFixer\Rules\DocBlockHeaderFixer()
    ])
    ->setRules([
        KonradMichalik\PhpDocBlockHeaderFixer\Generators\DocBlockHeader::fromComposer()->__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).