README

Reference implementation for TypeLang PHPDoc Parser.

Read documentation pages for more information.

Installation

TypeLang PHPDoc Parser is available as Composer repository and can be installed using the following command in a root of your project:

composer require type-lang/phpdoc

Supported Tags

@abstract - Declare any Element as abstract
@api - Highlight Element as being part of the public API
@author - TODO
@category - Used to organize groups of packages together
@copyright - Used to document the copyright information of any Element.
@deprecated - TODO
@example - TODO
@extends - Allows to extend templated classes and interfaces
@filesource - TODO
@final - Declare any Element as final
@global - TODO
@ignore - Used to tell documentation systems that Element are not to be processed.
@implements - Allows to extend templated interfaces
@inheritdoc - TODO
@inherits - An alias of @extends tag
@internal - TODO
@license - Used to indicate which license is applicable
@link - Indicates a custom relation between the associated Element and a website, which is identified by an absolute URI
@method - Allows a class to know which "magic" methods are callable
@mixin - TODO
@no-named-arguments - Indicates that argument names may be changed in the future.
@package - Used to categorize Element(s) into logical subdivisions
@override - Mention to see if the method is actually overriding a definition
@param - Used to document a single argument of a function or method
@param-closure-this - TODO
@param-immediately-invoked-callable - TODO
@param-later-invoked-callable - TODO
@param-out - TODO
@property - Used to declare which "magic" properties are supported
@property-read - Used to declare which "magic" properties are supported for reading
@property-write - Used to declare which "magic" properties are supported for writing
@pure-unless-callable-is-impure - TODO
@readonly - TODO
@require-extends - TODO
@require-implements - TODO
@return - Used to document the return value of functions or methods
@returns - An alias of @return tag
@seal-methods - TODO
@seal-properties - TODO
@see - Indicates a reference from the associated Symbol(s) to a website or other Symbol(s)
@since - TODO
@source - TODO
@subpackage - Used to categorize Element(s) into logical subdivisions
@suppress - TODO
@template - Allows classes (and class-like entries), functions and methods to declare a generic type parameter
@template-contravariant - Allows classes (and class-like entries), functions and methods to declare a generic contravariant type parameter
@template-covariant - Allows classes (and class-like entries), functions and methods to declare a generic covariant type parameter
@template-extends - An alias of @extends tag
@template-implements - An alias of @implements tag
@template-use - Allows to extend templated traits
@throw - An alias of @throws tag
@throws - Used to indicate whether Element throw a specific type of \Throwable (exception or error)
@todo - TODO
@unused-param - TODO
@use - An alias of @template-use tag
@used-by - TODO
@uses - TODO
@var - Document the Type of the following Element
@version - TODO

Psalm Tags

@psalm-allow-private-mutation - TODO
@psalm-api - Vendor-specific @api alias
@psalm-assert - TODO
@psalm-assert-if-false - TODO
@psalm-assert-if-true - TODO
@psalm-assert-untainted - TODO
@psalm-check-type - TODO
@psalm-check-type-exact - TODO
@psalm-consistent-constructor - TODO
@psalm-consistent-templates - TODO
@psalm-external-mutation-free - TODO
@psalm-extends - Vendor-specific @extends alias
@psalm-flow - TODO
@psalm-if-this-is - TODO
@psalm-ignore-falsable-return - TODO
@psalm-ignore-nullable-return - TODO
@psalm-ignore-var - TODO
@psalm-ignore-variable-method - TODO
@psalm-ignore-variable-property - TODO
@psalm-immutable - TODO
@psalm-implements - Vendor-specific @implements alias
@psalm-import-type - TODO
@psalm-inheritors - TODO
@psalm-internal - TODO
@psalm-method - Vendor-specific @method alias
@psalm-mutation-free - TODO
@psalm-no-seal-methods - TODO
@psalm-no-seal-properties - TODO
@psalm-override-method-visibility - TODO
@psalm-override-property-visibility - TODO
@psalm-param - Vendor-specific @param alias
@psalm-param-out - TODO
@psalm-property - Vendor-specific @property alias
@psalm-property-read - Vendor-specific @property-read alias
@psalm-property-write - Vendor-specific @property-write alias
@psalm-pure - TODO
@psalm-readonly - TODO
@psalm-readonly-allow-private-mutation - TODO
@psalm-require-extends - TODO
@psalm-require-implements - TODO
@psalm-return - Vendor-specific @return alias
@psalm-scope-this - TODO
@psalm-seal-methods - TODO
@psalm-seal-properties - TODO
@psalm-self-out - TODO
@psalm-stub-override - TODO
@psalm-suppress - TODO
@psalm-taint-escape - TODO
@psalm-taint-sink - TODO
@psalm-taint-source - TODO
@psalm-taint-specialize - TODO
@psalm-taint-unescape - TODO
@psalm-template - Vendor-specific @template alias
@psalm-template-contravariant - Vendor-specific @template-contravariant alias
@psalm-template-covariant - Vendor-specific @template-covariant alias
@psalm-this-out - TODO
@psalm-trace - TODO
@psalm-type - TODO
@psalm-use - Vendor-specific @use alias
@psalm-var - Vendor-specific @var alias
@psalm-variadic - TODO
@psalm-yield - TODO

PHPStan Tags

@phpstan-allow-private-mutation - TODO
@phpstan-assert - TODO
@phpstan-assert-if-false - TODO
@phpstan-assert-if-true - TODO
@phpstan-consistent-constructor - TODO
@phpstan-extends - TODO
@phpstan-ignore - TODO
@phpstan-ignore-line - TODO
@phpstan-ignore-next-line - TODO
@phpstan-immutable - TODO
@phpstan-implements - TODO
@phpstan-import-type - TODO
@phpstan-impure - TODO
@phpstan-method - Vendor-specific @method alias
@phpstan-param - Vendor-specific @param alias
@phpstan-param-closure-this - TODO
@phpstan-param-immediately-invoked-callable - TODO
@phpstan-param-later-invoked-callable - TODO
@phpstan-param-out - TODO
@phpstan-property - Vendor-specific @property alias
@phpstan-property-read - Vendor-specific @property-read alias
@phpstan-property-write - Vendor-specific @property-write alias
@phpstan-pure - TODO
@phpstan-pure-unless-callable-is-impure - TODO
@phpstan-readonly - TODO
@phpstan-readonly-allow-private-mutation - TODO
@phpstan-require-extends - TODO
@phpstan-require-implements - TODO
@phpstan-return - Vendor-specific @return alias
@phpstan-self-out - TODO
@phpstan-template - Vendor-specific @template alias
@phpstan-template-contravariant - Vendor-specific @template-contravariant alias
@phpstan-template-covariant - Vendor-specific @template-covariant alias
@phpstan-this-out - TODO
@phpstan-throws - Vendor-specific @throws alias
@phpstan-type - TODO
@phpstan-use - TODO
@phpstan-var - Vendor-specific @var alias

Phan Tags

@phan-abstract - Vendor-specific @abstract alias
@phan-assert - TODO
@phan-assert-false-condition - TODO
@phan-assert-if-false - TODO
@phan-assert-if-true - TODO
@phan-assert-true-condition - TODO
@phan-closure-scope - TODO
@phan-constructor-used-for-side-effects - TODO
@phan-extends - Vendor-specific @extends alias
@phan-file-suppress - TODO
@phan-forbid-undeclared-magic-methods - TODO
@phan-forbid-undeclared-magic-properties - TODO
@phan-hardcode-return-type - TODO
@phan-immutable - TODO
@phan-inherits - Vendor-specific @extends alias
@phan-method - Vendor-specific @method alias
@phan-mixin - TODO
@phan-output-reference - TODO
@phan-override - Vendor-specific @override alias
@phan-param - Vendor-specific @param alias
@phan-property - Vendor-specific @property alias
@phan-property-read - Vendor-specific @property-read alias
@phan-property-write - Vendor-specific @property-write alias
@phan-pure - TODO
@phan-read-only - TODO
@phan-real-return - TODO
@phan-return - Vendor-specific @return alias
@phan-side-effect-free - TODO
@phan-suppress-current-line - TODO
@phan-suppress-next-line - TODO
@phan-suppress-next-next-line - TODO
@phan-suppress-previous-line - TODO
@phan-template - Vendor-specific @template alias
@phan-transient - TODO
@phan-type - TODO
@phan-unused-param - TODO
@phan-var - Vendor-specific @var alias
@phan-write-only - TODO
@phanclosurescope - TODO

Quick Start

$parser = new \TypeLang\PHPDoc\Parser();
$result = $parser->parse(<<<'PHPDOC'
    /**
     * Example description {@see some} and blah-blah-blah.
     *
     * @Example\Annotation("foo")
     * @return array<non-empty-string, TypeStatement>
     * @throws \Throwable
     */
    PHPDOC);

var_dump($result);

Expected Output:

TypeLang\PHPDoc\DocBlock\DocBlock {
  +description: TypeLang\PHPDoc\DocBlock\Description\TaggedDescription {
    +components: array:3 [
      0 => TypeLang\PHPDoc\DocBlock\Description\Description {
        #value: "Example description "
      }
      1 => TypeLang\PHPDoc\DocBlock\Tag\SeeTag\SeeTag {
        +description: null
        +name: "see"
        +ref: TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\TypeSymbolReference {
          +type: TypeLang\Parser\Node\Stmt\NamedTypeNode { … }
        }
      }
      2 => TypeLang\PHPDoc\DocBlock\Description\Description {
        #value: " and blah-blah-blah.\n"
      }
    ]
  }
  +tags: array:3 [
    0 => TypeLang\PHPDoc\DocBlock\Tag\Tag {
      +description: TypeLang\PHPDoc\DocBlock\Description\Description {
        #value: "("foo")\n"
      }
      +name: "Example\Annotation"
    }
    1 => TypeLang\PHPDoc\DocBlock\Tag\ReturnTag\ReturnTag {
      +description: null
      +name: "return"
      +type: TypeLang\Parser\Node\Stmt\NamedTypeNode { … }
    }
    2 => TypeLang\PHPDoc\DocBlock\Tag\ThrowsTag\ThrowsTag {
      +description: null
      +name: "throws"
      +type: TypeLang\Parser\Node\Stmt\NamedTypeNode { … }
    }
  ]
}

Structural Elements

DocBlock

DocBlock is a representation of the comment object.

/**                                 |
 * Hello world                      | ← DocBlock's description.
 *                                  |
 * @param int $example              | ← DocBlock's tag #1.
 * @throws \Throwable Description   | ← DocBlock's tag #2.
 */                                 |

$description ― Provides a Description object.
$tags ― Provides a list of Tag objects.

/**
 * DocBlock structure pseudocode (real impl may differ)
 * 
 * @template-implements \Traversable<array-key, Tag>
 * @template-implements \ArrayAccess<array-key, Tag>
 */
class DocBlock
{
    public ?Description $description { get; }

    public iterable<array-key, Tag> $tags { get; }
}

Description

Description is a representation of the description object which may contain other tags.

/**
               ↓↓↓↓↓↓↓↓↓↓↓                         | ← This is a nested tag of the description.
 * Hello world {@see some} and blah-blah-blah.     |
   ↑↑↑↑↑↑↑↑↑↑↑             ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑     | ← This is part of the template.
 */

$tags ― Provides a list of Tag objects.
$components ― Provides a list of Tag|Description objects.

/**
 * Simple description structure pseudocode (real impl may differ)
 */
class Description implements \Stringable {}

/**
 * Tagged (composite) description structure pseudocode (real impl may differ)
 * 
 * @template-implements \Traversable<array-key, Tag>
 * @template-implements \ArrayAccess<array-key, Tag>
 */
class TaggedDescription extends Description implements 
    \Traversable, 
    \ArrayAccess,
    \Countable
{
    public iterable<array-key, Tag> $tags { get; }
    
    public iterable<array-key, Tag|Description> $components { get; }
}

Tag

A Tag represents a name (ID) and its contents.

/**
    ↓↓↓↓↓↓                                 | ← This is a tag name.
 * @throws \Throwable An error occurred.   |
           ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑   | ← This is tag description.
 */

$name ― Provides a tag's name (ID).
$description ― Provides an optional description of the tag.

/**
 * Common tag structure pseudocode (real impl may differ)
 */
class Tag implements \Stringable
{
    public non-empty-string $name { get; }

    public ?Description $description { get; }
}

/**
 * Throws tag structure pseudocode (real impl may differ)
 */
class ThrowsTag extends Tag
{
    public TypeStatement $type;
}

type-lang / phpdoc

Maintainers

Details