Nested arrays in generics "Template type T of method … is not referenced in a parameter."

[timdev]

https://phpstan.org/r/5a22c0b2-f31f-4b8c-b703-389222111268

I'm dealing with some code that does some hacky json_decode(json_encode(simplexml_load_string($xml)), true) stuff, and invariably runs into the single-element-array case.

I'm trying to properly annotate a method that helps in some of those cases. But I'm confused as to why PHPStan doesn't like it when the generic type is declared as possibly having inner array value.

Is this a bug, or am I not understanding something?

[ondrejmirtes]

With this signature:

     * @template T of array<string,mixed>
     * @param T|list<T> $recordOrListOfRecords
     * @return list<T>

PHPStan cannot know whether list<int> is supposed to be T or list<T>. So it doesn't know whether T should be resolved to int or list<int>.

Make simpler signatures without union types. Accept T in one function, and list<T> in a different function.

[ondrejmirtes]

Looks like this annotation would work as you expect: https://phpstan.org/r/17ba25e9-a8f8-4803-9139-75f5b4e5cf2c

[timdev]

Thanks for the explanation and suggestion.

I don't understand why PHPStan would be confused about list<int>. That should not a valid type for the parameter. (It's not T because doesn't have string keys, and it's not list<T> because int isn't an array of any kind).

The conditional-return suggestions doesn't really do what I want/expect. In my case, I want to constrain the possible types of $recordOrListOfRecords, and the conditional-return approach loosens it up. And I want PHPStan to retain knowledge of the particular array-shape type of T in the return.

Put another way, I have a function that roughly looks like : fn(array $x) => array_is_list($x) ? $x : [$x] (in reality it throws if $x is not a list or has any non-string keys). I want to both:

• Constrain the parameter type to array<string,mixed>|list<array<string,mixed>>, and
• Represent that the shape of the array<string,mixed> in the return-type is the same same shape as the array<string,mixed> in the parameter.

I've taken a route around the issue for now, but will try to revisit and see if I can make any progress. I'm pretty sure that PHPStan is actually smarter than I am in this instance, and that I'm missing something.

[ondrejmirtes]

I don't understand why PHPStan would be confused about list<int>

And yet it is. To the engine passing list<int> into T|list<T> is ambiguous. That's why you need a conditional return type instead.