Improves array list typing and validation

[JasonTheAdams]

This is a quick follow that improves how lists are validated and type checked within the code.

array_is_list polyfill

This adds a polypill for array_is_list and validates incoming arrays that should be lists. This is important for serialization to arrays and, especially, JSON — as [0 => 'foo', 2 => 'bar'] is considered an object in JSON, whereas it would be an array in PHP. This helps protect against any strange conversions.

List Typing

I learned something interesting that string[] (and like syntax) is not the same as list<string>. Apparently string[] is an alias for array<int, string> — which simply states that the key is an integer, not that the array is actually a list. The list<string> syntax is more strict and states that the array is, in fact, a list.

The improved typing allows for removing a phpstan-ignore that was otherwise necessary.

[felixarntz]

@JasonTheAdams The validation LGTM, but what is that list<...> syntax about? That seems pointless and unusual to me.

[felixarntz]

@JasonTheAdams OK, I should have read your PR description before my review 🤦

Still, I'm wondering whether we should go with that - I have never seen it on any project. FWIW every project within the WordPress ecosystem I've seen using PHPStan is doing it wrong then. I'd like to see a major project embrace this weird syntax before we commit to it - it seems wildly unintuitive to me. Not sure who thought it was a great idea to say string[] is the same as array< int, string >.

Honestly, so far I'd feel inclined to keep the PHPStan ignore in place - going back to a point I said before, PHPStan can also become annoying and get in the way sometimes.

[JasonTheAdams]

Hey @felixarntz!

I can appreciate the frustration with PHPStan. It can be like that friend that feels the need to correct your wording. Not usually wrong, but annoying. 😆

So this actually isn't a PHPStan quirk, though, and it part of the broader PHPDoc spec. You can see this used in project such as Symfony: https://github.com/symfony/symfony/blob/693311f60f3f3da60d002d9b37ccaa6d06d63257/src/Symfony/Component/Process/Process.php#L1242

Lists just don't exist in PHP like they do in languages such as Python, and declaring an array's key still doesn't indicate it to be a list. This doc type gives a way of indicating an array as a true list type, and PHPStan performs the helpful (and sometimes annoying) check. The idea of bringing lists to PHP has come up multiple times and is why the array_is_list function was created in the first place — the term "list" being used here indicating its acknowledgement and meaning by the PHP team.

Hope this helps! 😄

[felixarntz]

@JasonTheAdams Thank you for the detailed explanation! Makes sense to go with this then.

That being said, I'm sure we're not the only ones this is news to. It may be something worth clarifying - basically, never (?) use T[], but always use list<T>. (I don't think there would ever be a way where we would want to support array<int, T> where the integers are not sequential, for example because when JSON encoding such a thing it becomes an object. How do you feel about putting that in our docs somewhere?

[JasonTheAdams]

Thanks, @felixarntz! I went ahead and added a section to the CONTRIBUTING doc for this. 👍