README

Introduction
Requirements
Installation
Documentation Publishing
- Automatic Documentation Publishing
Usage
Local Development
Contributing

Introduction

A PHP AST visitor for automatically generating or updating docblocks in PHP source code.

Requirements

PHP 7.1 or higher.

Installation

Install Zerotoprod\DocgenVisitor via Composer:

composer require zero-to-prod/docgen-visitor

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/docgen-visitor)
vendor/bin/zero-to-prod-docgen-visitor

# Publish to custom directory
vendor/bin/zero-to-prod-docgen-visitor /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-docgen-visitor"
        ],
        "post-update-cmd": [
            "zero-to-prod-docgen-visitor"
        ]
    }
}

Usage

Here's how you can use DocgenVisitor to read a PHP file, process its contents, and then write the updated code back to the same file:

<?php

require 'vendor/autoload.php';

use PhpParser\Node;
use PhpParser\NodeTraverser;
use PhpParser\ParserFactory;
use Zerotoprod\DocgenVisitor\DocgenVisitor;

$comments = ['This is an updated class docblock'];
$changes = []; // This is used to accumulate changes from the DocgenVisitor
$traverser = new NodeTraverser();
$traverser->addVisitor(
    new DocgenVisitor(
        function (Node $node) {
            // Filter comments to specific types
            if ($node instanceof Node\Stmt\Class_) use ($comments) {
                return $comments;
            }
            return [];
        },
        $changes
    )
);

// Apply the visitor to a php file.
$traverser->traverse(
    (new ParserFactory())->createForHostVersion()
        ->parse(file_get_contents('User.php'));
);

$updatedCode = null;
foreach ($changes as $change) {
    // Replace the old docblock text with the new one
    $updatedCode = substr_replace(
        $originalCode,
        $change->text,
        $change->start,
        $change->end - $change->start + 1
    );
}

file_put_contents($filePath, $updatedCode);

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 / docgen-visitor

Maintainers

Details