Docblock Generator

The DocBlockGenerator is a developer-experience (DX) tool that bridges the gap between your documentation definitions and your IDE. It provides full autocompletion for request properties that are otherwise handled via “magic” getters.

The Problem

In Apivalk, request data is populated into bags. While you can access data using $request->getBody()->get('name'), the framework also supports magic getters like $request->name. Without extra metadata, IDEs (like PhpStorm) won’t know that name exists or what type it is.

The Solution: Automated DocBlocks

The DocBlockGenerator automates the creation of this metadata. It performs the following steps for every Request class in your project:

1. Discovery: Scans your API directories for classes extending AbstractApivalkController.
2. Extraction: Executes the getRequestClass() and getRoute() methods on the Controller to find the associated Request class and its properties.
3. Shape Generation: Creates “Shape” classes (e.g., GetUserBodyShape, GetUserSortingShape, GetUserFilteringShape) in a Shape/ subdirectory. These classes contain public properties representing your documentation and route-defined sorting/filtering.
4. Rewrite: Updates the original Request class file with @method tags pointing to these Shape classes.

Example Result

Before running the generator, your Request class might look like this:

class GetUserRequest extends AbstractApivalkRequest {
    // Empty class
}

After running DocBlockGenerator, it is automatically updated to:

/**
 * @method \apivalk\apivalk\Http\Request\Parameter\ParameterBag|Shape\GetUserQueryShape query()
 * @method \apivalk\apivalk\Http\Request\Parameter\ParameterBag|Shape\GetUserPathShape path()
 * @method \apivalk\apivalk\Http\Request\Parameter\ParameterBag|Shape\GetUserBodyShape body()
 * @method \apivalk\apivalk\Router\Route\Sort\SortBag|Shape\GetUserSortingShape sorting()
 * @method \apivalk\apivalk\Router\Route\Filter\FilterBag|Shape\GetUserFilteringShape filtering()
 * @method \apivalk\apivalk\Router\Route\Pagination\Paginator|null paginator()
 */
class GetUserRequest extends AbstractApivalkRequest {
    // Still empty, but now with IDE support!
}

Now, in your controller, you can type $request->body()-> and your IDE will suggest all defined properties with their correct types.

How to Run

You can trigger the generation process from your bootstrap or a CLI tool:

use apivalk\apivalk\Documentation\DocBlock\DocBlockGenerator;

$generator = new DocBlockGenerator();
$generator->run(
    '/path/to/your/api/src', 
    'App\\Api'
);

Components

• DocBlockGenerator: The main entry point that iterates over classes.
• DocBlockRequestGenerator: Converts an AbstractApivalkRequest into a DocBlockRequest data object.
• DocBlockRequest: Holds the metadata for the shapes (Body, Query, Path, Sorting, Filtering).
• DocBlockShape: Generates the PHP code for the Shape classes.
• DocBlockResourceGenerator / DocBlockResource: Generates @property annotations for AbstractResource subclasses so you get IDE autocompletion on $resource->name, $resource->status, etc.
• DocBlockResourceRequestGenerator / DocBlockResourceRequest: For each AbstractListResourceController, generates a typed per-resource list request (e.g. AnimalListRequest) with @method annotations for sorting(), filtering(), and paginator() wired to shape interfaces derived from the resource’s availableSortings() / availableFilters().

Resource DocBlock Generation

When DocBlockGenerator encounters an AbstractResourceController subclass, it produces two extra artifacts:

1. Resource @property docblock — written once per resource class so that $animal->name, $animal->type, etc. autocomplete in your IDE.
2. Per-resource list request — for each AbstractListResourceController, a typed request class (e.g. Api/v1/Animal/Request/AnimalListRequest.php) with @method annotations pointing at generated sorting/filtering shape interfaces. If the file already exists, only the docblock is updated — your class body is preserved.

This gives you full IDE autocompletion on $request->sorting()->status, $request->filtering()->createdAt, and $request->paginator() without writing the boilerplate yourself.