README

Php DocBlock Header Fixer

PHP-CS-Fixer ships rules for DocBlock content and spacing, but none of them add or enforce header annotations such as @author and @license before a class, interface, trait or enum. Keeping those in sync by hand means every renamed class or licence change turns into a manual find-and-replace across the codebase. This package adds a configurable PHP-CS-Fixer rule that generates and enforces the annotations you configure, while leaving the rest of an existing DocBlock, descriptions, other tags, ordering untouched.

✨ Features

Configurable annotations: add any tag (@author, @license, @template, @phpstan-type, …), each enforced or appended independently
Composer autodiscovery: fromComposer() reads authors and licence straight from composer.json, so the header never drifts from the package metadata
Preserves existing DocBlocks: descriptions, other tags and ordering survive; only the configured annotations are enforced
Structure name summaries: optionally prepend the class, interface, trait or enum name as the DocBlock's first line, with stale-name replacement on rename
PHP-CS-Fixer compatible: avoids conflicts with phpdoc_no_package, phpdoc_separation and no_blank_lines_after_phpdoc

🔥 Installation

Requirements

PHP 8.2, 8.3, 8.4 or 8.5
ext-tokenizer (bundled with PHP by default)
friendsofphp/php-cs-fixer ^3.14 (installed automatically as a dependency)

Composer

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

🚀 Quick start

<?php
// ...
return (new PhpCsFixer\Config())
    // ...
    ->registerCustomFixers([
        new KonradMichalik\PhpDocBlockHeaderFixer\Rules\DocBlockHeaderFixer(),
    ])
    ->setRules([
        KonradMichalik\PhpDocBlockHeaderFixer\Generators\DocBlockHeader::fromComposer(addStructureName: true)->toArray(),
    ])
;

Running php-cs-fixer fix now turns

<?php

class MyClass
{
    public function myMethod(): void {}
}

into

<?php
/**
 * MyClass.
 *
 * @author Jane Doe <jane@example.com>
 * @license MIT
 */
class MyClass
{
    public function myMethod(): void {}
}

The same happens for interfaces, traits and enums. See Usage for the plain-array and object-oriented alternatives to fromComposer().

📚 Documentation

Topic	What's inside
Usage	Registering the fixer: plain array, object-oriented builder, and `fromComposer()` autodiscovery
Configuration	Every option with its type, default and effect

🧑‍💻 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

Package info

Security

Statistics