{"id":1629,"date":"2016-02-22T10:57:13","date_gmt":"2016-02-22T09:57:13","guid":{"rendered":"https:\/\/www.entropywins.wtf\/blog\/?p=1629"},"modified":"2018-07-31T13:03:02","modified_gmt":"2018-07-31T12:03:02","slug":"missing-in-php7-collections","status":"publish","type":"post","link":"https:\/\/www.entropywins.wtf\/blog\/2016\/02\/22\/missing-in-php7-collections\/","title":{"rendered":"Missing in PHP7: Collections"},"content":{"rendered":"

This is the fourth post in my Missing in PHP7 series<\/a>. The previous one is about Value Objects<\/a>.<\/p>\n

In this post I’ll outline some problems PHP has with regards to collections, the implications of those problems, and a few mitigation strategies.<\/p>\n

PHP arrays<\/strong><\/p>\n

PHPs main collection type is the associative array. These arrays can be used as maps and lists, and form the jack of all trades that is used for nearly all PHP collections.<\/p>\n

$oldArray = array( 'pink' => 'fluffy', 'unicorns' ); \/\/ PHP <= 5.3\n$newArray = [ 'pink' => 'fluffy', 'unicorns' ]; \/\/ PHP > 5.3<\/pre>\n
It’s possible to type hint against array, including return types as of PHP7.<\/p>\n
function magicArrayModify( array $inputValues ): array {\n    \/\/ This is where the magic happens\n    return $outputValues;\n}<\/pre>\n
Problem 1: lackluster type hinting<\/strong><\/p>\n
There are collections that contain values of multiple types, such as maps containing configuration. Many collections however are meant to hold only a specific type of value. While for scalar values, it is possible to type hint and get all the benefits from static code analysis, the collections, the only thing you can say with code is that they are collections.<\/p>\n
Luckily there is a standardized way to specify such types in doc blocks, which is understood by many tools.<\/p>\n
\/**\n * @param string[] $inputValues\n * @return string[]\n *\/\nfunction magicArrayModify( array $inputValues ): array {}<\/pre>\n
This approach has some drawbacks. Firstly, it’s documentation, which can easily get out of sync with the actual code. Secondly, while it provides much-needed information to static code analysis tools, PHP itself ignores violations of the contracts specified in these docs.<\/p>\n
Trick: improved type hinting<\/strong><\/p>\n
As of PHP 5.6, there is a way to type hint against arrays of a specific type with code for parameters. This is done by means of variable-length argument lists<\/a>.<\/p>\n
function haveSomeStrings( string ...$inputValues ) {}\n\nhaveSomeStrings( ...$awesomeStrings );<\/pre>\n
You can easily refactor existing code to follow this approach. The only thing you need to do is add the unpacking operator to the arguments in the calls to the function. When I first tried this out, I was surprised by how many of the callers did not actually pass in a variable length collection. Most of these being in tests. So far, I’ve removed more no longer needed arrays, than having to add the unpacking operator. Example:<\/p>\n
function testSomething() {\n    haveSomeStrings( [ 'foo', 'bar', 'baz' ] );\n    \/\/ Some assertions\n}\n\nfunction testSomething() {\n    haveSomeStrings( 'foo', 'bar', 'baz' );\n    \/\/ Some assertions\n}<\/pre>\n
Some people argue you should wrap all collections (be it in PHP or not), which certainly helps with the lack of proper collection type hinting in PHP. This trick is especially nice for the constructors of such wrappers.<\/p>\n
The unpacking operator also works for traversables, which makes this approach partially mitigate the next problem.<\/p>\n
Problem 2: arrays and Traversable<\/strong><\/p>\n
PHPs Traversable<\/code> interface is the base interface for everything that can be looped though. It gets extended by Iterator<\/code> and Generator<\/code> and is implemented by dozens of classes in PHPs standard library. Iterators are awesome, as I’ve written about before in Lazy iterators in PHP and Python<\/a> and Some fun with iterators<\/a>.<\/p>\n
Unfortunately it’s not that simple. There is one data structure that is traversable but does not implement Traversable<\/code>: PHPs main collection type array<\/code>. This means that traversables cannot be given to a function with an array<\/code> type hint, and arrays cannot be given to a function with a Traversable<\/code> type hint.<\/p>\n
function haveSomeStrings( array $inputValues ) {\n    foreach ( $inputValues as $value ) {\n        echo 'Wow. Such string. Many omg';\n    }\n}\n\nhaveSomeStrings( $stringTraversable ); \/\/ Boom!<\/pre>\n
\"Double<\/p>\n
This is really silly, as a lot of these functions work with both, without trying, if not for the type hint. The type hint can of course be dropped, though then again we end up with the documentation downside, and also run into the problem that the documentation cannot specify “Traversable of type”.<\/p>\n
\/**\n * @param string[]|Traversable $inputValues\n *\/\nfunction haveSomeStrings( $inputValues ) {\n    foreach ( $inputValues as $value ) {\n        echo 'Wow. Such string. Many omg';\n    }\n}<\/pre>\n
I ranted about this before in my Lazy iterators in PHP and Python post<\/a>.<\/p>\n
Edit: I’m very happy that PHP 7.1 has fixed this issue by introducing the iterable pseudo-type<\/a>.<\/p>\n
Additional thoughts<\/strong><\/p>\n
In this post I’ve focused on type hinting, as I felt\u00a0this is most in line with the goals of this blog post series<\/a>, and that these problems are both less known and less written about than other Collection features PHP misses. Things such as generics and a better PHP standard collection library are of course very welcome.<\/p>\n
Not everyone agrees that type hinting is a wise practice. My personal opinion is that it is generally good, and that it’s extremely bad to not be able to do it at all. This blog post is written from that perspective. If you have a different opinion, feel free to shout at me in a comment.<\/p>\n
See also<\/strong><\/p>\n