Incorrect type resolution (parentheses, generic, etc.)

[rainbow-alex]

<?php

require "vendor/autoload.php";

$comment = '/**
 * @return (string|Apple)
 */';

$block = new \phpDocumentor\Reflection\DocBlock($comment);
var_dump($block->getTagsByName("return")[0]->getType()); // \(string|\Apple)

$block = new \phpDocumentor\Reflection\DocBlock($comment, new \phpDocumentor\Reflection\DocBlock\Context("A"));
var_dump($block->getTagsByName("return")[0]->getType()); // \A\(string|\A\Apple)

Generic types are parsed incorrectly as well; and there may be other issues. Since PSR-5 is still a draft, I didn't expect 100% compliance, but the values returned now are pretty useless. Not getting correctly parsed types blocks my project, so I'd gladly help out with this.

The current API for getting types is getType: string and getTypes: Type\Collection (the latter basically being string[]). Unfortunately, PSR-5's types are more complicated... As a consumer I want an API that allows me to handle complex types. Something like:

interface TypeInterface
class ScalarType implements TypeInterface {
    public function getType() // 'string', 'int', etc.
}
class ArrayOfType implements TypeInterface {
    public function getItemType() // TypeInterface of the items
}
class GenericType implements TypeInterface {
    public function getTemplateType()
    public function getParameterTypes()
}
...

I think this belongs in the ReflectionDocBlock library, but I'd like some feedback before I implement this.

[cebe]

why do you wrap return types in parenthesis? Common syntax is @return string|Apple

[rainbow-alex]

(type|type|...) is valid according to PSR-5, even if it the parentheses are redundant. I was just giving a minimal example of invalid type parsing. (type|type)[] or type<type> don't parse correctly either.

[hediet]

@rainbow-alex I've started to implement such a type library (https://github.com/hediet/php-type-reflection) to support a unified way to reflect types.
However, since I was unsure how to denote generic types, my type parser is quite improvisational.
Generic types and union types are currently not implemented but I am on it...

[rainbow-alex]

@hediet You should really check out PSR-5! It's a draft but I would base my implementation on that: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types

I think we should hear what the guys from ReflectionDocBlock+PSR-5 have to say on this. I don't know how 'final' PSR-5 actually is or if they have anything in the works. I appreciate the effort though :)

[boenrobot]

There is the getTypes() (notice the "s") method, which returns the possible types in an array.

That said, it does not allow a detailed handling of collections. E.g. there's no easy way to get the type(s) of a key or value in a collection, or anything more "inner".

The reason there's no such collection handling is primarily because that part is not finalized in PSR-5.

[hediet]

@rainbow-alex PSR-5 has spoiled the concept of generics by their definition of "generic":

generic          = collection-type "<" [type-expression "," *SP] type-expression ">"

which restricts the arity of a generic type definition to 2 and their domain to collections by defining the semantics of the first and second type argument. What about generic callbacks (e.g. callable<int, int, void>, a function which takes two ints and returns nothing) or dependency injection stuff (e.g. Factory)? Besides, at least netbeans does not recognize "ArrayCollection" as being an "ArrayCollection", thus if the generic type argument is specified there is no autocompletion any more.
(For this reason my parser will support an optional whitespace between the type and the first "<")

[boenrobot]

There's a separate discussion on that here.

[rainbow-alex]

@boenrobot I think it's safe to say that finalization of PSR-5 is not going to happen overnight. So, as an intermediary measure, perhaps we can implement something like ->getUnparsedType() which returns the type as is?

[boenrobot]

That's what getType() does, no?

[rainbow-alex]

no, getType tries to resolve the type, and as I initially reported, it doesn't do it properly.

[boenrobot]

Oh... right. Sorry. I thought we had fixed this, but now I remembered #21 was never merged.

[rainbow-alex]

No problem. I am currently getting by. I worked around it by using new Context("#") and then doing a str_replace("\\#\\", "", ...) on getType(). It ain't pretty but it gets the job done pending a fix on your end.

[felixfbecker]

I really need generics support. Currently everywhere I write Promise<Whatever> I'm getting a warning that Promise<Whatever> is not a valid FQSEN.
Could it be that the root issue here is that this package tries to parse the type with a regular expression (which can only parse context-free languages) while the PSR5 type syntax with parenthesis etc. is clearly not context-free? It should be parsed with a lexer/tokenizer instead

[jaapio]

I'm closing this issue because we created a separate component for type-resolving which is fully psr-5 complient however the generics are not defined yet. Please feel free to open a issue there to continue this discussion.