README

Introduction
Requirements
Installation
Documentation Publishing
- Automatic Documentation Publishing
Usage
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.

Documentation Publishing

You can publish this README to your local documentation directory.

This can be useful for providing documentation for AI agents.

This can be done using the included script:

# Publish to default location (./docs/zero-to-prod/docblock-annotator)
vendor/bin/zero-to-prod-docblock-annotator

# Publish to custom directory
vendor/bin/zero-to-prod-docblock-annotator /path/to/your/docs

Automatic Documentation Publishing

You can automatically publish documentation by adding the following to your composer.json:

{
    "scripts": {
        "post-install-cmd": [
            "zero-to-prod-docblock-annotator"
        ],
        "post-update-cmd": [
            "zero-to-prod-docblock-annotator"
        ]
    }
}

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.

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

zero-to-prod / docblock-annotator

Maintainers

Details