berlioz/php-doc

Berlioz PhpDoc

dev-develop 2019-01-16 11:24 UTC

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
  • 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);