Simple PHP documentation comment parser. First, install it via composer as follows:
composer require stein197/doxer
And then use it like this:
$docblock = <<<DOC
/**
* Description.
* Another line
* of description.
* @param int \$age Age parameter.
* @param string \$name Name
* parameter.
* @return Person The person.
* @throws Exception In case of errors.
*
DOC;
$doc = new Stein197\Doxer\Doc($docblock);
if ($doc->exists()) { // Checks for existance
$doc->getDescription(); // "Description. Another line of description."
foreach ($doc->getTags() as $tag) { // Returns and array of Stein197\Doxer\Tag instances
$tag->getDescription(); // Handles multiple lines of description
$tag->getName(); // Returns the name of the tag without "@" char
foreach ($tag->getProperties() as $name => $value) { // Returns an array of properties
"$name=$value"; // Tag's properties such as "version", "type", etc.
}
}
}
Each docblock comment can have tags which start with @
sign and each tag can have an array of properties and an optional description. The next list shows which tags are currently supported:
- @author
<name>
[<email>]
- @deprecated
[<version>]
[<description>]
- @license
[<url>]
[<description>]
- @link
<uri>
[<description>]
- @param
<type>
<name>
[<description>]
- @return
<type>
[<description>]
- @see
<uri>
[<description>]
- @since
<version>
[<description>]
- @var
<type>
[<name>]
[<description>]
- @uses
<uri>
[<description>]
- @throws
<type>
[<description>]
So for example if tag "@return string A string" is parsed, it's properties will only contain type
entry:
$returnTag = (new Stein197\Doxer\Doc('/** @return string A string */'))->getTags()[0];
$returnTag->getDescription(); // "A string"
$returnTag->getProperties(); // ['type' => 'string']
But if the tag does not match any of predefined, then it will be parsed as @tag [<description>]
. So for example if tag "@nonexistent string A string" is parsed, all it will contain is a description:
$tag = (new Stein197\Doxer\Doc('/** @nonexistent string A string */'))->getTags()[0];
$tag->getDescription(); // "string A string"
$tag->getProperties(); // null
If tag to be parsed can have properties but has incorrect syntax, properties and description will be nulls:
$tag = (new Stein197\Doxer\Doc('/** @param a b c d */'))->getTags()[0];
$tag->getDescription(); // null
$tag->getProperties(); // null
NOTE! If tag accepts name property which will start with
$
sign (@param
,@var
tags), then after retrievingname
property the name will be retrieved without leading "$":
$doc = new Stein197\Doxer\Doc('/** @param Type $arg1 */');
$doc->getTags()[0]->getProperties(); // ['name' => 'arg1']
The only class that is supposed to be used is Stein197\Doxer\Doc
, which accepts a docblock string as the only constructor parameter. Then the next methods could be used:
Method | Return type | Description |
---|---|---|
getDescription() |
string |
Returns docblock description or null if it's not present |
getTags(?string $name = null) |
Stein197\Doxer\Tag[] |
Returns an array of tags or null if there are no tags present. If optional parameter is passed then only tags with matching name will be retrieved |
exists() |
bool |
Returns true if doc exists. Even empty description block treats as existing one |
The next table contains list of Stein197\Doxer\Tag
public methods:
Method | Return type | Description |
---|---|---|
getDescription() |
string |
Returns tag description or null if it's not present |
getName() |
string |
Returns the name of a tag without leading @ sign |
getProperties() |
string[] |
Returns an array of tag properties or null if there are no properties |
getProperty(string $name) |
string |
Returns single property value or null if there is no such property |
To run unit tests call the test
composer script:
composer run test