Docblock Laravel Package

Getting Started

Install the package via Composer: composer require phpowermove/docblock. Start by parsing a simple DocBlock using the DocBlock class:

use PhpPowerMove\DocBlock\DocBlock;

$doc = new DocBlock('/** @param string $name @return void */');
$tags = $doc->getTags(); // Returns array of tag objects
$param = $tags['param'][0] ?? null; // First @param tag

The shortest path to value is integrating it into reflection-based workflows—e.g., when analyzing method signatures for validation or documentation tools. Begin by examining the DocBlock constructor and its getSummary(), getDescription(), and getTags() methods in the source.

Implementation Patterns

• Reflection Integration: Pair with ReflectionMethod/ReflectionClass to hydrate custom metadata. Example: Extract @todo tags from controller actions for a CLI task list.
• Type-Driven Logic: Use Tag::getTypes() to access typed metadata (e.g., @var int<1,10>) for schema validation or schema inference in CLI or API tools.
• Custom Annotations: Extend the parser by iterating over Tag objects to implement domain-specific annotations (e.g., @route("/users")) without bloating core logic.
• Static Analysis Pipeline: Feed parsed DocBlocks into a visitor pattern for custom sniffers—detect missing @return tags, enforce consistent @throws usage, or validate parameter naming.

Gotchas and Tips

• Null Safety: getTags() returns an associative array keyed by tag name, not by position—even single tags like @param are arrays. Always check isset($tags['param']) or use null coalescing.
• Whitespace Quirks: Leading asterisks (*) are stripped, but inconsistent spacing (e.g., mixed tabs/spaces) can break tag detection; run DocBlock::normalize() if pre-processing raw comments.
• No Native Type Parsing: While it extracts types from @param, @var, etc., it does not parse complex union types (int|string) into structured data—you’ll need to split them manually or integrate with a type parser.
• No @method Support: The library ignores @method by default. Override Tag::create() in a custom DocBlockFactory if you need method-level metadata.
• Performance Tip: For bulk parsing (e.g., scanning thousands of files), reuse the same DocBlock instance and call reset() between invocations to avoid memory churn.