Reflection Docblock Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require phpdocumentor/reflection-docblock
   

2. Basic Usage:

   use phpdocumentor\Reflection\DocBlockFactory;
   
   $factory = DocBlockFactory::createInstance();
   $docblock = $factory->create('/** @var string $name */');
   

First Use Case: Parsing Class DocBlocks

$reflectionClass = new ReflectionClass(MyClass::class);
$docblock = $factory->create($reflectionClass->getDocComment());
$summary = $docblock->getSummary(); // Class description

Key Entry Points

• DocBlockFactory::createInstance() → Singleton factory
• $docblock->getTags() → Access all tags (e.g., @param, @return)
• $docblock->getSummary()/getDescription() → Class/method descriptions

Implementation Patterns

1. Tag-Specific Parsing

// Extract @param tags
$paramTags = $docblock->getTagsByName('param');
foreach ($paramTags as $tag) {
    $type = $tag->getType(); // e.g., "string"
    $var = $tag->getVariableName(); // e.g., "$name"
    $description = $tag->getDescription(); // e.g., "User's full name"
}

2. Dynamic DocBlock Generation

// Build a docblock from scratch
$docblock = $factory->create('/** @var array<int, string> */');
$docblock->setSummary('A list of items');
$docblock->addTag($factory->createTag('@return', 'void'));

3. Integration with Laravel

Use Case: Dynamic API Responses

// In a controller/middleware
$docblock = $factory->create($request->getRoute()->getAction()['controller']);
$responseTags = $docblock->getTagsByName('return');
$responseSchema = collect($responseTags)->pluck('description')->first();

Use Case: Validation Rules from DocBlocks

// In a Form Request
$docblock = $factory->create($this->validator->rules());
$paramTags = $docblock->getTagsByName('param');
foreach ($paramTags as $tag) {
    $this->rules[$tag->getVariableName()] = $tag->getType(); // e.g., 'email'
}

4. Custom Tag Handlers

// Extend for custom annotations (e.g., @api-version)
$factory->addTagFactory(new class implements TagFactory {
    public function createTag(string $name, array $content): Tag {
        return new CustomTag($name, $content);
    }
});

Gotchas and Tips

Pitfalls

1. Deprecated Features (v6+)

   • Avoid @param tags without variables (e.g., @param string Description).
   • Static factories are deprecated; use DocBlockFactory directly.

2. Type Resolution Limits

   • Complex generics (e.g., array<array-key, mixed>) may return InvalidTag.
   • Workaround: Use phpdocumentor/type-resolver for advanced types.

3. Multiline Descriptions

   • Indented lines in descriptions (e.g., @param $name\n * \n * Indented text) may break.
   • Fix: Normalize whitespace with trim() or preg_replace('/\s+/', ' ', $text).

Debugging Tips

• Validate DocBlocks:

  if (!$docblock->isValid()) {
      throw new \RuntimeException('Invalid docblock: ' . $docblock->getErrors());
  }
  

• Inspect Raw Content:

  $rawContent = $docblock->getContent(); // Debug original input
  

• Tag Existence Checks:

  if ($docblock->hasTag('return')) {
      // Safe to access $docblock->getTagsByName('return')
  }
  

Performance

• Cache Factories:

  $factory = DocBlockFactory::createInstance(); // Singleton; reuse
  

• Avoid Reparsing: Store parsed docblocks in a static cache or Laravel’s cache() helper.

Extension Points

1. Custom Tag Parsing Override TagFactory for non-standard annotations (e.g., @deprecated-since).

2. Type Resolver Integration

   $typeResolver = new \phpdocumentor\TypeResolver();
   $resolvedType = $typeResolver->resolve($tag->getType());
   

3. Laravel Service Provider Bind the factory to the container:

   $this->app->singleton(DocBlockFactory::class, fn() => DocBlockFactory::createInstance());
   

Laravel-Specific Quirks

• Route DocBlocks: Use Route::getMethods() + Route::getAction() to fetch controller docblocks dynamically.
• Artisan Commands: Parse docblocks in help text:

  $this->output->writeln($docblock->getSummary());