[php] Support array generics in doc comments

[stollr]

Description

Netbeans already supports the array notation in form of Type[] (e.g. @return DateTime[]) in return and param doc comments and respects it for autocomplete. But PHP does not support this as a return type declaration (until now). It only supports array as return type.

So it is more naturally to document this as array<Type> (e.g. @return array<DateTime>. This notation is also supported by PHPStan and Psalm. It is more flexible as it allows to declarate the type of the array key, too:

array<int, Type>

Sometimes you do not have a native array, but an object which is iterable and you want to declare those types, too. PHP supports the type iterable. So this notations should be supported, too:

iterable<Type>
iterable<int, Type>

It would be great if Netbeans would add support for this notations.

Use case/motivation

Here's an example:

<?php
class Example {
    /**
     * @return array<DateTime>
     */
    function dateTimes(): array {
        return [new DateTime('yesterday'), new DateTime('today')];
    }
}

$example = new Example();
foreach ($example->dateTimes() as $instanceOfDateTime) {
    $instanceOfDateTime-> // shows autocomplete list, with methods of class "DateTime"
}

Related issues

No response

Are you willing to submit a PR?

• [ ] Yes I am willing to submit a PR!

Code of Conduct

• [X] I agree to follow the Apache Software Foundation's Code of Conduct

[mvorisek]

Also, until generics like Product<Car> is fully supported, the <Car> part should be ignored/stripped and Product should be honored, eg. handled as a non generics class, with class usage & hinting should be supported.

[stollr]

@mvorisek I like your idea, but I'd say that is out of scope of this feature request. I'd suggest to create a separate issue for that.

[mvorisek]

here is - https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/src/DocBlock/TypeExpression.php - battle proven regex/grammar to parse all possible phpdoc tags incl. generic/nested/conditonal tags

[terax6669]

PHPStorm supports generics, Laravel uses them. I'm sure there's more examples. Even though this isn't strictly a PHP feature, it's used in real projects and helps a lot. This should be a priority to implement.

Example class: https://github.com/laravel/framework/blob/11.x/src/Illuminate/Collections/Collection.php

/**
 * @template TKey of array-key
 *
 * @template-covariant TValue
 *
 * @implements \ArrayAccess<TKey, TValue>
 * @implements \Illuminate\Support\Enumerable<TKey, TValue>
 */
class Collection implements ArrayAccess, CanBeEscapedWhenCastToString, Enumerable