Improve type information when PHPDoc type and PHP type available

JordanMele1

PHP types are good for enforcing types at runtime, however they currently do not provide the "full story" regarding the data shape. The best example of this is the array type. It is common that PHPDoc will be used to better describe the array contents, e.g.;

string[] - Array of string
(string|string[])[] - Array of string and string[]
[int, string][] - Array of int and string tuples (array of arrays), not sure about the syntax here
string[][] - Array of string[].

Less frequently used syntax the expands type hinting to array indexes;

string[int] - Array of string where indexes are all int (useful when indexes will be used later on)

JordanMele1

Started off expecting this to cover more than just arrays, but it quickly occurred to me that most other cases we covered well.

JakubMisek

Hello @JordanMele1 , that's a good idea. Mostly we follow the PHPDocumentor standards so the syntax won't break the standard. Are there any common ways of doing it in some other projects? Thanks!

JordanMele1

No real consensus on these complex types as best I can tell due to the lack of any standard other than PHPDocumentor.
Closest there probably is to a standard on this is likely buried in the shelved PSR-5 which at least covers most of the above cases (my ABNF reading ability is rusty though, so I could be wrong). https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#arrays.

Certain aspects of the syntax above (particularly tuples) are inspired by TypeScript syntax, Would be worth keeping an eye on PHP 8 type evolutions here, there does not appear to be any array syntax changes however union types (no doubt based on PHPDoc) may offer some guidance on what the future holds.

JakubMisek

I see two syntaxes that we don't support and we should:

(string|int)[] an array of union
@var A&B $x type intersection

and them some kind of structures; usually something like

/**
 * @var array $x {
 *     @type X Y
 *  }