Rule to force syntax of array notation in PHPDocs

[julienfalque]

In PHPDocs, there are two possible syntaxes for array values:

/**
 * @param Foo[] $arrayOfFoos
 */

/**
 * @param array<Foo> $arrayOfFoos
 */

For consistence I think it would be nice to have a rule that forces a single syntax.

[Wirone]

FYI: such fixer exists, but there is one scenario when it breaks the valid annotation.

[ruudk]

For what it's worth: Since 8.1 we have the concept of list in PHP.

That makes Foo[] ambiguous because is it could be:

• a list
• an array where the key is important

So to me, that only makes the following flavors possible:

/**
 * @param array<string, Foo> Key is important, and it's a string
 * @param array<int, Foo>    Key is important, and it's an integer
 * @param list<Foo>          It's a list, only values are important, everything is indexed from 0
 */

I hope to find a rule that automatically converts Foo[] to list<Foo>. Then, PHPstan will propably fail when it's not what you want. It will move you towards changing it to array<type-of-the-key, Foo>, where you have to think about what the type of the key is.

[Wirone]

@ruudk thank you for the input! Personally I am not sure if it matters that much, list<Foo> is almost the same as array<Foo> (implicit int keys) or array<int, Foo> with a slight difference you can be sure that integers in keys consecutive numbers from 0 up. Mentioned fixer from @kubawerlos does minimal job and keeps exact same intent, because in Foo[] you also assume int keys in an array and you don't know if it's a list - it's just an iterable collection of Foo. I believe it could be done as strategy within that fixer - being able to use array or list for initial conversion 🙂.

[keradus]

myself, I would love to forbid usage of Foo[] or array<Foo> and instead use list<Foo>, iterable<Foo>, array<keyType, Foo> or array{Foo, Foo, Foo} (tuple).

array is very overpacked and one cannot be sure what they will deal with, when receiving it..

---

above is different than normalization of Foo[] <> array<Foo>. I see possibility for that unification, but with my input on top, I would skip step of that unification and start migrating away from overpacked array metatype

[Wirone]

@keradus I believe that your preference is out of the scope of this particular issue / feature request. Even though it may be valid, it's something more strict that not everyone in userland is interested in. This issue is about standardising the format of array types in phpDoc, not about making it more strict, which is IMHO a separate thing, more for tools like PHPStan than Fixer.

[keradus]

you can treat my comment as:

• eagerness of having even stronger rule instead of one proposed
• not preventing originally proposed rule to be going in
  • yet... if, for example, I were implementing sth myself, i would only implement the stronger rule (Because of my preference)

yes, we can keep original idea of unification open, no harm in it. just no commitment into implementing it by community since 2019 🤷🏻

[Wirone]

just no commitment into implementing it by community since 2019 🤷🏻

Actually it was implemented 2 years ago, but not in the core 😉. Why it was done like this is a separate story.

[keradus]

if it matters in context of main repo, we can either have own implementation (not sure if makes sense), incorporate custom rule to main repo (suggested for rules in general few times, some owners raised some of rules to be incorporated to main repo ;) ), or say it's not worth to implement due to userland solution.

I doubt it makes sense to keep this idea open, if we are not progressing on it for so many years. let's be realistic :)

[Wirone]

I doubt it makes sense to keep this idea open, if we are not progressing on it for so many years. let's be realistic :)

I agree, I kept this issue open only because I was hoping that @kubawerlos is open to migrate this fixer to the core (himself, or by letting others to do it), that's why it has "easy pick" label. If it's not the case, then I believe we should close this.