berlioz/php-doc

Berlioz PhpDoc

Berlioz PhpDoc

, _(*1)

Berlioz PhpDoc is a PHP library to read the documentations in code (classes, methods and functions) with advanced annotation interpretation., _(*2)

Installation

Composer

You can install Berlioz PhpDoc with Composer, it's the recommended installation., _(*3)

$ 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)., _(*4)

To use it, you need to pass the cache manager in first argument of PhpDocFactory class., _(*5)

$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., _(*6)

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, _(*7)

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, _(*8)

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, _(*9)

Tags

Formats

Some tags formats are supported by library and the value returned by DocBlock class is a PHP code and not string., _(*10)

Example:, _(*11)

/**
 * 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:, _(*12)

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, _(*13)

Extends

You can extends tags and declare them to the parser. Yours tags must implements TagInterface interface., _(*14)

$phpDocFactory = new PhpDocFactory;
$phpDocFactory->getParser()->addTagClass('tagName', MyTagClass::class);