README

Introduction
Requirements
Installation
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.

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