zero-to-prod/docblock-annotator

An annotator for PHP docblocks.

v4.0.0 2025-02-16 00:00 UTC

Requires

• php: >=8.1
• nikic/php-parser: ^5.0
• zero-to-prod/docgen-visitor: ^1.0
• zero-to-prod/filesystem: ^0.1.0

Requires (Dev)

• mikey179/vfsstream: ^1.6
• phpunit/phpunit: <12.0

MIT

• David Smith

• zero-to-prod
• docblock-annotator

README

Contents

• Introduction
• Requirements
• Installation
• Usage
  • Instantiation
  • updateDirectory
  • updateFiles
• Local Development
• Contributing

Introduction

An annotator for PHP docblocks.

Requirements

• PHP 7.4 or higher.

Installation

Install Zerotoprod\DocblockAnnotator via Composer:

composer require zero-to-prod/docblock-annotator

This will add the package to your project’s dependencies and create an autoloader entry for it.

Usage

Instantiation

Create a new DocblockAnnotator instance with your desired configuration:

use Zerotoprod\DocblockAnnotator\DocblockAnnotator;
use Zerotoprod\DocblockAnnotator\Statement;
use Zerotoprod\DocblockAnnotator\Modifier;
use PhpParser\ParserFactory;

$DocblockAnnotator = new DocblockAnnotator(
    modifiers: [Modifier::public],
    statements: [Statement::ClassMethod], // can also handle raw string: class_method
    success: fn(string $file, string $value) => echo "Updated: $file",
    failure: fn(Throwable $e) => echo $e->getMessage(),
    (new ParserFactory)->createForHostVersion()
);

Arguments:

• modifiers: Array of visibility modifiers to target
  • public
  • protected
  • private
• statements: Array of statement types to process
  • class_method
  • const
  • class
  • class_const
  • enum_case
  • enum
  • function
  • trait
  • property
  • interface
• success: Callback function executed after successful file processing
• failure: Callback function executed when an error occurs
• Parser: Optional PHP-Parser instance (defaults to host PHP version)

updateDirectory

Updates docblocks in all PHP files within a directory.

use Zerotoprod\DocblockAnnotator\DocblockAnnotator;

/* @var DocblockAnnotator $DocblockAnnotator */
$DocblockAnnotator->updateDirectory(
    comments: ['@link https://github.com/zero-to-prod/docblock-annotator'],
    directory: 'src',
    recursive: true
);

updateFiles

Updates docblocks for a specified array of files.

use Zerotoprod\DocblockAnnotator\DocblockAnnotator;

/* @var DocblockAnnotator $DocblockAnnotator */
$DocblockAnnotator->updateFiles(
    comments: ['@link https://github.com/zero-to-prod/docblock-annotator'],
    files: ['src/MyClass.php', 'src/AnotherClass.php']
);

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.

1. Fork the repository.
2. Create a new branch (git checkout -b feature-branch).
3. Commit changes (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature-branch).
5. Create a new Pull Request.