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.

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 everything the configuration does not mention (descriptions, other annotations, ordering). The configured annotations themselves are enforced: an existing occurrence is rewritten to the configured value and duplicates of the same tag are collapsed. One exception: an annotation sitting on the opening (/**) or closing (*/) line of an existing DocBlock is left alone, because rewriting it would take the delimiter with it. Set to false to discard the existing DocBlock entirely and rebuild it from the configuration.
separate (string, default: 'none'): Add blank lines ('top', 'bottom', 'both', 'none')
add_structure_name (boolean, default: false): Add the structure name as first line in the DocBlock. An existing first line that consists of a bare identifier followed by a dot is treated as that slot and rewritten, so a renamed class does not accumulate its former name.
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

Package info

Statistics

Security