Weave Code
Reflection Docblock Laravel Package
phpdocumentor/reflection-docblock
Parse and reflect PHPDoc DocBlocks with a factory-based API. Fully compatible with the PHPDoc standard, it extracts summaries, descriptions, and tags, enabling libraries to read documentation metadata and build annotation-like features from doc comments.
phpdocumentor/reflection-docblock is a PHPDoc-compatible DocBlock parser from the phpDocumentor ecosystem. It lets you reliably parse doc comments into a structured DocBlock object, making it easy to read summaries, descriptions, and tags—ideal for tooling, annotation-style metadata, and documentation workflows.
Create a DocBlockFactory via createInstance() and call create() with a raw doc comment or any object exposing getDocComment() (e.g., ReflectionClass) to turn PHPDoc text into rich, queryable data.
- 100% PHPDoc standard compatibility
- Parses summary, description, and tags into objects
- Works with raw strings or reflection sources (
getDocComment()) - Clean API via DocBlockFactory and DocBlock
- Suitable for annotations and static analysis/documentation tools
Frequently asked questions about Reflection Docblock
- How do I install phpdocumentor/reflection-docblock in a Laravel project?
- Run `composer require phpdocumentor/reflection-docblock` in your project root. The package has no Laravel-specific dependencies and integrates cleanly with Composer’s autoloader. Ensure your `composer.json` targets PHP 8.1+ for full compatibility.
- Can this package parse DocBlocks from ReflectionClass or ReflectionMethod objects?
- Yes. Use `DocBlockFactory::createInstance()` to create a factory, then pass a Reflection object (e.g., `ReflectionClass::getDocComment()`) to the `create()` method. The factory automatically detects and parses the docblock from the reflection.
- What Laravel use cases benefit from structured DocBlock parsing?
- Ideal for API documentation (e.g., auto-generating Swagger/OpenAPI specs from route annotations), dynamic validation (parsing `@assert` tags), or Scout/Elasticsearch metadata indexing. Works with Laravel Nova for admin panel tooltips or custom validation rules.
- Does this support custom tags like `@laravel-role` or `@api-resource`?
- Yes, but you’ll need to register custom tag handlers via `DocBlockFactory::addTagHandler()`. For framework-specific tags, extend the base `Tag` class or use the `InvalidTag` fallback for unsupported formats. Check the [phpDocumentor docs](https://www.phpdoc.org/) for handler examples.
- Will this work with PHP 8.4 and Laravel 10+?
- Yes, the package is actively maintained for PHP 8.4+. Laravel 10’s PHP 8.4 support is fully compatible, though test edge cases like multiline tag descriptions or complex generics (e.g., `@template`) if using advanced PHPDoc features.
- How do I cache parsed DocBlocks to avoid runtime overhead?
- Cache the `DocBlock` objects using Laravel’s `Cache` facade. Store the parsed result (e.g., `cache()->remember('docblock_'.get_class($reflection), ...)`) with a long TTL. Avoid parsing per-request unless absolutely necessary—pre-compute during boot or in a queue job.
- Are there breaking changes between v5 and v6 of this package?
- Yes. Version 6 deprecated `StaticFactory` in favor of `DocBlockFactory::createInstance()`. If upgrading, update your codebase to use the new factory method. Pin to `^6.0` in `composer.json` to avoid unintended major upgrades and test thoroughly for deprecated methods.
- Can I use this with PHPStan or Psalm for static analysis?
- Yes, but monitor for dependency conflicts. `phpdocumentor/type-resolver` (a dependency) may interact with PHPStan/Psalm’s type systems. Test your setup with `phpstan analyze` or `psalm --init` to catch conflicts early. Use `replace` in `composer.json` if version mismatches occur.
- How do I handle deprecated PHPDoc syntax (e.g., `@param $var type`)?
- The package enforces modern PHPDoc standards. Use `@param mixed $var` or `@param string $var` instead. For legacy code, implement a pre-processing step (e.g., a Laravel service provider) to normalize docblocks before parsing, or suppress warnings with `@deprecated` tags.
- What alternatives exist for DocBlock parsing in Laravel?
- For lightweight needs, consider `rubix/ml-extras` (for ML annotations) or `doctrine/annotations` (Doctrine-specific). For PHPDoc compliance, this package is the most robust. If you need runtime annotation processing, explore `symfony/property-info` (works with Symfony’s PropertyAccess) or `php-ai/php-ai` for AI-driven docblock generation.
Weaver
How can I help you explore Laravel packages today?