Switch phpdoc libraries

[j6s]

Currently, phparch (or - more accurately, the DocBlockTypeAnnotations Visitor) uses phpdocumentor in order to parse PHPDoc comments and it's TypeResolver in order to resolve the symbols in these comments to fully qualified names.

The problem is, that the TypeResolver version used by the current stable version of phpdocumentor does not handle arrays of multiple types (e.g. (Foo|Bar)[] or (Foo|null)[]). There is a beta version of the type resolver and phpdocumentor that handle this, but there has been very little action there. Additionally, many other libraries depend on the current version of phpdocumentor - so most environments probably already have a dependency that prevents this library from simply building on top of beta / new versions.

All of this leads me to believe that something else should be used in order to parse docblocks.
In a quick research I found the following libraries that could be helpful. Further research must be done.

• parsing docblocks
  • https://packagist.org/packages/barryvdh/reflection-docblock
    • Seems to be a fork / related project of phpdocumentors reflections-docblock currently used but without the type parsing.
  • https://packagist.org/packages/doctrine/annotations
    • Only in this list because it is a symfony component. Used wildly, maybe it can be used for pure parsing without the annotation functionality
  • https://packagist.org/packages/gossi/docblock
• parsing types
  • https://packagist.org/packages/serenata/docblock-type-parser
    - Not sure if this can resolve class imports using the use statement
• other
  • https://packagist.org/packages/php-di/phpdoc-reader
    • Seems like this can do both

Requirements for a type resolver:

• Given a classname and a context it should be able to resolve a fully qualified name, resolving all imports / use statements.
• Should support nullable types @return ?Foo
• Should support simple array syntax @return Foo[]
• Should support compound array syntax @return (Foo|Bar)[]
• Should support alternate array syntax @return array<Foo>
• Optional: Support for generic type annotations @return Collection<Foo>

For reference:
https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md