jawira / annotation-updater

v1.1.0 2026-09-14 14:59 UTC

Requires

• php: ^8.2
• friendsofphp/php-cs-fixer: ^3.0

Requires (Dev)

• jawira/skeleton: ^2.32
• phpunit/phpunit: ^11.5.56
• vimeo/psalm: ^6.16.1

MIT

• Jawira Portugal

• phpdoc
• annotation
• dev
• php-cs-fixer

Published on Packagist.org on 2026-09-14 15:13 UTC

README

This PHP-CS-Fixer rule helps you manage PHPDoc tags
in classes, interfaces, traits, and enums.

Installation

composer require --dev jawira/annotation-updater

Usage

Registering the fixer

In your .php-cs-fixer.php register and configure AnnotationUpdater:

1. Use Config::registerCustomFixers() to register an instance of AnnotationUpdater.
2. Use Config::setRules() to specify fixer's configuration under the Jawira/annotation_updater key.

Example:

<?php

use Jawira\AnnotationUpdater\AnnotationUpdater;
use PhpCsFixer\Config;

return (new Config())
  ->registerCustomFixers([
    new AnnotationUpdater(),
  ])
  ->setRules([
    'Jawira/annotation_updater' => [
      'annotations' => [
        ['tag' => 'author', 'value' => 'John Connor', 'mode' => 'preserve'],
        ['tag' => 'license', 'value' => 'MIT', 'mode' => 'replace'],
        ['tag' => 'todo', 'mode' => 'remove'],
      ],
    ],
  ]);

This is the result after executing the previous configuration:

/**
 * @author Sarah Connor
- * @license proprietary
- * @todo add type hints
+ * @license MIT
 */
class Example{
}

Configuration

The fixer accepts a single configuration key: annotations. This is an array of annotation rules to apply.

Each rule is an array with the following structure.

• tag: The PHPDoc tag name without the @.
• value: The value of the tag. Do not set this key for remove mode!
• mode: One of preserve, replace, or remove.

Example:

[
  'tag' => 'author',
  'value' => 'John Connor',
  'mode' => 'preserve',
]

Mode

The fixer has three different modes:

1. preserve: Do not replace a tag if it is already present. If the tag is missing, it will be added. For example, this mode can add an @author tag to classes that do not already have one.
2. replace: Always replace the tag with the configured value. This updates the value of existing tags and adds the tag when it is not present.
3. remove: Remove the tag if it is present. This is useful for deleting unwanted tags, such as @todo.

The mode behavior is summarized in the following table.

Mode	Tag is not present	Tag is present
preserve	Add tag	Do nothing
replace	Add tag	Replace tag
remove	Do nothing	Remove tag

Contributing

• If you like this project, ⭐ star it on GitHub.
• Or, follow me on 𝕏.
• Found a bug? Please report it by opening an issue!

License

This library is licensed under the MIT license.

Disclaimer

• Yes, I know that annotations are not the same as PHPDoc tags, but when I realized this, it was too late. Properly speaking, this library updates PHPDoc tags, not annotations.
• This project is inspired by konradmichalik/php-doc-block-header-fixer.

Packages from jawira

jawira/doctrine-diagram-bundle

Symfony Bundle to generate database diagrams.

jawira/case-converter

Convert strings between 13 naming conventions: Snake case, Camel case, Pascal case, Kebab case, Ada case, Train case, Cobol case, Macro case, Upper case, Lower case, Sentence case, Title case and Dot notation.

more...