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 of Berlioz\PhpDoc\DocBlock
PhpDocFactory::getClassDoc() returns a Berlioz\PhpDoc\DocBlock\ClassDocBlock object
PhpDocFactory::getPropertyDoc() returns a Berlioz\PhpDoc\DocBlock\PropertyDocBlock object
PhpDocFactory::getMethodDoc() returns a Berlioz\PhpDoc\DocBlock\MethodDocBlock object
PhpDocFactory::getFunctionDoc() returns a Berlioz\PhpDoc\DocBlock\FunctionDocBlock object

Some methods are available with DocBlock object:

DocBlock::getTitle() returns the title part in the PhpDoc
DocBlock::getDescription() returns the description part in the PhpDoc
DocBlock::getTags() returns all tags presents in the PhpDoc
DocBlock::getTag() returns a tag present in the PhpDoc
DocBlock::hasTag() returns if a tag is present in the PhpDoc

Additional methods are available with extended DocBlockclass:

Berlioz\PhpDoc\DocBlock\FunctionDocBlock:
- FunctionDocBlock::getName(): returns the full name of function
- FunctionDocBlock::getShortName(): returns the short name of function
- FunctionDocBlock::getNamespaceName(): returns the namespace name of function
- FunctionDocBlock::getClassName(): returns the name of class
- FunctionDocBlock::isDisabled(): known if function is disabled
- FunctionDocBlock::isUserDefined(): known if it's user defined function
- FunctionDocBlock::isInternal(): known if function is internal
- FunctionDocBlock::isClosure(): known if function is a closure
- FunctionDocBlock::isDeprecated(): known if function is deprecated
- FunctionDocBlock::isGenerator(): known if function is generator
- FunctionDocBlock::isVariatic(): known if function is variatic
Berlioz\PhpDoc\DocBlock\ClassDocBlock:
- ClassDocBlock::getName(): returns the full name of class
- ClassDocBlock::getShortName(): returns the short name of class
- ClassDocBlock::getNamespaceName(): returns the namespace name of class
- ClassDocBlock::isAbstract(): known if class is abstract
- ClassDocBlock::isFinal(): known if class is final
- ClassDocBlock::isInternal(): known if class is internal
- ClassDocBlock::isUserDefined(): known if it's user defined class
- ClassDocBlock::isAnonymous(): known if class is anonymous
- ClassDocBlock::isCloneable(): known if class is cloneable
- ClassDocBlock::isInstantiable(): known if class is instantiable
- ClassDocBlock::isInterface(): known if class is an interface
- ClassDocBlock::isIterable(): known if class is iterable
- ClassDocBlock::isIterateable(): known if class is iterateable
- ClassDocBlock::isTrait(): known if class is a trait
Berlioz\PhpDoc\DocBlock\PropertyDocBlock:
- PropertyDocBlock::getName(): returns the full name of property
- PropertyDocBlock::getShortName(): returns the short name of property
- PropertyDocBlock::getNamespaceName(): returns the namespace name of class
- PropertyDocBlock::getClassName(): returns the name of class
- PropertyDocBlock::isPublic(): known if property has public visibility
- PropertyDocBlock::isProtected(): known if property has protected visibility
- PropertyDocBlock::isPrivate(): known if property has private visibility
- PropertyDocBlock::isStatic(): known if property is static
- PropertyDocBlock::isDefault(): known if property is default
Berlioz\PhpDoc\DocBlock\MethodDocBlock:
- MethodDocBlock::getName(): returns the full name of method
- MethodDocBlock::getShortName(): returns the short name of method
- MethodDocBlock::getNamespaceName(): returns the namespace name of class
- MethodDocBlock::getClassName(): returns the name of class
- MethodDocBlock::isConstructor(): known if method is constructor
- MethodDocBlock::isDestructor(): known if method is destructor
- MethodDocBlock::isPublic(): known if method has public visibility
- MethodDocBlock::isProtected(): known if method has protected visibility
- MethodDocBlock::isPrivate(): known if method has private visibility
- MethodDocBlock::isStatic(): known if method is static
- MethodDocBlock::isAbstract(): known if method is abstract
- MethodDocBlock::isFinal(): known if method is final
- MethodDocBlock::isUserDefined(): known if it's user defined method
- MethodDocBlock::isInternal(): known if method is internal
- MethodDocBlock::isClosure(): known if method is a closure
- MethodDocBlock::isDeprecated(): known if method is deprecated
- MethodDocBlock::isGenerator(): known if method is generator
- MethodDocBlock::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);

berlioz / php-doc

Maintainers

Details