jasny / phpdoc-parser
Jasny skeleton library
Installs: 273 907
Dependents: 9
Suggesters: 0
Security: 0
Stars: 40
Watchers: 3
Forks: 7
Open Issues: 2
Requires
- php: >=7.4.0
- jasny/php-functions: ^3.3
Requires (Dev)
- jasny/php-code-quality: ~2.7.0
- phpunit/phpunit: >= 9.0.0
This package is auto-updated.
Last update: 2024-11-09 14:45:21 UTC
README
Jasny PHPDoc parser
Configurable DocBlock parser from PHP.
The PHPDoc parser allows you to configure tags including the method how to parse and extract information. This is inline with phpDocumentor style annotations and differs from for instance Doctrine type annotations.
Installation
composer require jasny/phpdoc-parser
Usage
/** * The description of foo. This function does a lot of thing * which are described here. * * Some more text here. * * @important * @uses FooReader * @internal Why this isn't part of the API. * Multi-line is supported. * * @param string|callable $first This is the first param * @param int $second The second one * @return void * @throws InvalidArgumentException * @throws DoaminException if first argument is not found */ function foo($first, int $second) { // ... }
Parse annotations
use Jasny\PhpdocParser\PhpdocParser; use Jasny\PhpdocParser\Set\PhpDocumentor; use Jasny\PhpdocParser\Tag\FlagTag; $doc = (new ReflectionFunction('foo'))->getDocComment(); $customTags = [ new FlagTag('important') ]; $tags = PhpDocumentor::tags()->with($customTags); $parser = new PhpdocParser($tags); $meta = $parser->parse($doc);
The result will be the following:
[ 'summery' => "The description of foo", 'description' => "The description of foo. This function does a lot of thing which are described here.\n\nSome more text.", 'important' => true, 'uses' => 'FooReader', 'internal' => "Why this isn't part of the API. Mutlti-line is supported", 'params' => [ 'first' => [ 'type' => "string|callable", 'name' => "first", 'description' => "This is the first parm" ], 'second' => [ 'type' => "int", 'name' => "second", ] ], 'return' => 'void' ]
Tags
The following tags are included in PhpDocumentor::tags()
:
@api
@author
@copyright
@deprecated
@example
@ignore
@internal
@link
@method
(all methods will be grouped inmethods
array)@package
@param
(all params will be grouped inparams
array)@property
(all properties will be grouped inproperties
array)@property-read
(also inproperties
array)@property-write
(also inproperties
array)@return
@see
@since
@throws
(all exceptions will be grouped inthrows
array)@todo
@uses
@used-by
@var
If you only need to parse those tags, you can simply do:
use Jasny\PhpdocParser\PhpdocParser; use Jasny\PhpdocParser\Set\PhpDocumentor; //$doc = ...; Get doc-comment string from reflection $tags = PhpDocumentor::tags(); $parser = new PhpdocParser($tags); $meta = $parser->parse($doc);
Tags classes
Here's a list of available tags classes:
- Summery
- ArrayTag
- CustomTag
- DescriptionTag
- ExampleTag
- FlagTag
- MapTag
- MethodTag
- ModifyTag
- MultiTag
- NumberTag
- RegExpTag
- VarTag
- WordTag
FQSEN Resolver
FQSEN stands for Fully Qualified Structural Element Name
. FQSEN convertor is used to expand class name or function name to fully unique name (so with full namespace). For example, Foo
can be converted to Zoo\\Foo\\Bar
.
Such convertors are used in this lib. Some tags, that deal with variable types, or classes names, support adding them as a constructor parameter.
For example, TypeTag
, that can be used for parsing @return
tag, has the following constructor: TypeTag($name, $fqsenConvertor = null)
. If provided, convertor expands the type, given as type of returned value in doc-comment. If ommited, the type will stay as it is in doc-comment.
Convertor can be provided in one of two ways:
$tags = PhpDocumentor::tags($fn)
- for all the tags, predefined inPhpDocumentor::tags()
$tags = $tags->add(new TypeTag('footag', $fn))
- for all the tags, that are explicitly added to predefined, it should be passed as a constructor parameter (if it is supported by constructor).
After that create the parser from the tags as $parser = new PhpdocParser($tags)
.
The resolver function should accept a class name and return an expanded name.
Example
This example uses phpDocumentor/TypeResolver.
use Jasny\PhpdocParser\PhpdocParser; use Jasny\PhpdocParser\Set\PhpDocumentor; use phpDocumentor\Reflection\Types\ContextFactory; use phpDocumentor\Reflection\FqsenResolver; $reflection = new ReflectionClass('\My\Example\Classy'); $contextFactory = new ContextFactory(); $context = $contextFactory->createFromReflector($reflection); $resolver = new FqsenResolver(); $fn = fn(string $class): string => $resolver->resolve($class, $context); $tags = PhpDocumentor::tags($fn); $parser = new PhpdocParser($tags); $doc = $reflection->getDocComment(); $meta = $parser->parse($doc);