berlioz / php-doc
Berlioz PhpDoc is a PHP library to read the documentations in code (classes, methods and functions) with advanced annotation interpretation.
Installs: 7 777
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: ^7.1 || ^8.0
- ext-json: *
- ext-mbstring: *
- psr/log: ^1.0
- psr/simple-cache: ^1.0
Requires (Dev)
- phpunit/phpunit: ^7.4 || ^8.0 || ^9.0
README
Berlioz PhpDoc is a PHP library to read the documentations in code (classes, methods and functions) with advanced annotation interpretation.
Installation
Composer
You can install Berlioz PhpDoc with Composer, it's the recommended installation.
$ composer require berlioz/php-doc
Dependencies
- PHP ^7.1 || ^8.0
- Packages:
- psr/simple-cache
- psr/log
Usage
Basic
$phpDocFactory = new PhpDocFactory; // To get class PhpDoc $doc = $phpDocFactory->getClassDoc(ClassOfMyProject::class); // To get class property PhpDoc $doc = $phpDocFactory->getPropertyDoc(ClassOfMyProject::class, 'myProperty'); // To get class method PhpDoc $doc = $phpDocFactory->getMethodDoc(ClassOfMyProject::class, 'myMethod'); // To get function PhpDoc $doc = $phpDocFactory->getFunctionDoc('myFunction');
Cache
The library supports PSR-16 (Common Interface for Caching Libraries).
To use it, you need to pass the cache manager in first argument of PhpDocFactory
class.
$simpleCacheManager = new MySimpleCacheManager; $phpDocFactory = new PhpDocFactory($simpleCacheManager);
So you do disk i/o economies and your application will be faster than if you don't use cache manager.
Berlioz\PhpDoc\DocBlock class
A DocBlock
class or an array of them are returned when you call these methods of factory:
PhpDocFactory::getClassDocs()
returns an array ofBerlioz\PhpDoc\DocBlock
PhpDocFactory::getClassDoc()
returns aBerlioz\PhpDoc\DocBlock\ClassDocBlock
objectPhpDocFactory::getPropertyDoc()
returns aBerlioz\PhpDoc\DocBlock\PropertyDocBlock
objectPhpDocFactory::getMethodDoc()
returns aBerlioz\PhpDoc\DocBlock\MethodDocBlock
objectPhpDocFactory::getFunctionDoc()
returns aBerlioz\PhpDoc\DocBlock\FunctionDocBlock
object
Some methods are available with DocBlock
object:
DocBlock::getTitle()
returns the title part in the PhpDocDocBlock::getDescription()
returns the description part in the PhpDocDocBlock::getTags()
returns all tags presents in the PhpDocDocBlock::getTag()
returns a tag present in the PhpDocDocBlock::hasTag()
returns if a tag is present in the PhpDoc
Additional methods are available with extended DocBlock
class:
Berlioz\PhpDoc\DocBlock\FunctionDocBlock
:FunctionDocBlock::getName()
: returns the full name of functionFunctionDocBlock::getShortName()
: returns the short name of functionFunctionDocBlock::getNamespaceName()
: returns the namespace name of functionFunctionDocBlock::getClassName()
: returns the name of classFunctionDocBlock::isDisabled()
: known if function is disabledFunctionDocBlock::isUserDefined()
: known if it's user defined functionFunctionDocBlock::isInternal()
: known if function is internalFunctionDocBlock::isClosure()
: known if function is a closureFunctionDocBlock::isDeprecated()
: known if function is deprecatedFunctionDocBlock::isGenerator()
: known if function is generatorFunctionDocBlock::isVariatic()
: known if function is variatic
Berlioz\PhpDoc\DocBlock\ClassDocBlock
:ClassDocBlock::getName()
: returns the full name of classClassDocBlock::getShortName()
: returns the short name of classClassDocBlock::getNamespaceName()
: returns the namespace name of classClassDocBlock::isAbstract()
: known if class is abstractClassDocBlock::isFinal()
: known if class is finalClassDocBlock::isInternal()
: known if class is internalClassDocBlock::isUserDefined()
: known if it's user defined classClassDocBlock::isAnonymous()
: known if class is anonymousClassDocBlock::isCloneable()
: known if class is cloneableClassDocBlock::isInstantiable()
: known if class is instantiableClassDocBlock::isInterface()
: known if class is an interfaceClassDocBlock::isIterable()
: known if class is iterableClassDocBlock::isIterateable()
: known if class is iterateableClassDocBlock::isTrait()
: known if class is a trait
Berlioz\PhpDoc\DocBlock\PropertyDocBlock
:PropertyDocBlock::getName()
: returns the full name of propertyPropertyDocBlock::getShortName()
: returns the short name of propertyPropertyDocBlock::getNamespaceName()
: returns the namespace name of classPropertyDocBlock::getClassName()
: returns the name of classPropertyDocBlock::isPublic()
: known if property has public visibilityPropertyDocBlock::isProtected()
: known if property has protected visibilityPropertyDocBlock::isPrivate()
: known if property has private visibilityPropertyDocBlock::isStatic()
: known if property is staticPropertyDocBlock::isDefault()
: known if property is default
Berlioz\PhpDoc\DocBlock\MethodDocBlock
:MethodDocBlock::getName()
: returns the full name of methodMethodDocBlock::getShortName()
: returns the short name of methodMethodDocBlock::getNamespaceName()
: returns the namespace name of classMethodDocBlock::getClassName()
: returns the name of classMethodDocBlock::isConstructor()
: known if method is constructorMethodDocBlock::isDestructor()
: known if method is destructorMethodDocBlock::isPublic()
: known if method has public visibilityMethodDocBlock::isProtected()
: known if method has protected visibilityMethodDocBlock::isPrivate()
: known if method has private visibilityMethodDocBlock::isStatic()
: known if method is staticMethodDocBlock::isAbstract()
: known if method is abstractMethodDocBlock::isFinal()
: known if method is finalMethodDocBlock::isUserDefined()
: known if it's user defined methodMethodDocBlock::isInternal()
: known if method is internalMethodDocBlock::isClosure()
: known if method is a closureMethodDocBlock::isDeprecated()
: known if method is deprecatedMethodDocBlock::isGenerator()
: known if method is generatorMethodDocBlock::isVariatic()
: known if method is variatic
Tags
Formats
Some tags formats are supported by library and the value returned by DocBlock
class is a PHP code and not string.
Example:
/** * Test doc. * * My description of my method. * Multi-line. * * @test false * @novalue * @value Only text * @test2("test", param1=true, param2="test", param3={"test":"test"}) * @value Second text * @jsonTest {"test":"test"} * @jsonArrayTest [{"test":"test"}, {"test2":"test2"}] */
The result of DocBlock::getTags()
method is:
array(6) {
["test"]=>
array(1) {
[0]=>
object(Berlioz\PhpDoc\Tag) (2) {
["name":"Berlioz\PhpDoc\Tag":private]=>
string(4) "test"
["value":"Berlioz\PhpDoc\Tag":private]=>
bool(false)
}
}
["novalue"]=>
array(1) {
[0]=>
object(Berlioz\PhpDoc\Tag) (2) {
["name":"Berlioz\PhpDoc\Tag":private]=>
string(7) "novalue"
["value":"Berlioz\PhpDoc\Tag":private]=>
NULL
}
}
["value"]=>
array(2) {
[0]=>
object(Berlioz\PhpDoc\Tag) (2) {
["name":"Berlioz\PhpDoc\Tag":private]=>
string(5) "value"
["value":"Berlioz\PhpDoc\Tag":private]=>
string(9) "Only text"
}
[1]=>
object(Berlioz\PhpDoc\Tag) (2) {
["name":"Berlioz\PhpDoc\Tag":private]=>
string(5) "value"
["value":"Berlioz\PhpDoc\Tag":private]=>
string(11) "Second text"
}
}
["test2"]=>
array(1) {
[0]=>
object(Berlioz\PhpDoc\Tag) (2) {
["name":"Berlioz\PhpDoc\Tag":private]=>
string(5) "test2"
["value":"Berlioz\PhpDoc\Tag":private]=>
array(4) {
[0]=>
string(4) "test"
["param1"]=>
bool(true)
["param2"]=>
string(4) "test"
["param3"]=>
object(stdClass) (1) {
["test"]=>
string(4) "test"
}
}
}
}
["jsonTest"]=>
array(1) {
[0]=>
object(Berlioz\PhpDoc\Tag) (2) {
["name":"Berlioz\PhpDoc\Tag":private]=>
string(8) "jsonTest"
["value":"Berlioz\PhpDoc\Tag":private]=>
object(stdClass) (1) {
["test"]=>
string(4) "test"
}
}
}
["jsonArrayTest"]=>
array(1) {
[0]=>
object(Berlioz\PhpDoc\Tag) (2) {
["name":"Berlioz\PhpDoc\Tag":private]=>
string(13) "jsonArrayTest"
["value":"Berlioz\PhpDoc\Tag":private]=>
array(2) {
[0]=>
object(stdClass) (1) {
["test"]=>
string(4) "test"
}
[1]=>
object(stdClass) (1) {
["test2"]=>
string(5) "test2"
}
}
}
}
}
Available tags
Some tags are available by default:
Berlioz\PhpDoc\Tag\ParamTag
Berlioz\PhpDoc\Tag\ReturnTag
Berlioz\PhpDoc\Tag\VarTag
Extends
You can extends tags and declare them to the parser. Yours tags must implements TagInterface interface.
$phpDocFactory = new PhpDocFactory; $phpDocFactory->getParser()->addTagClass('tagName', MyTagClass::class);