PHP's list() is asking for a class
PHP has a weird mechanism for achieving multiple return values with the list
function. It lets you do things like this:
<?php
function severalThings() {
return ['thing', 'another thing', 'one more thing'];
}
list($foo, $bar, $foobar) = severalThings();
This is quite commonly used in some codebases, but I think it’s bad style.
Firstly, because PHP doesn’t offer a concrete way to let the user of a function
know exactly what it’s returning, it may not be clear what you’re getting from
that array. The function could even not return an array at all, in which case
trying to use list on its return value will silently set your variables to
null.
At least in PHP 7 we can now guarantee that the function will return an array, but we still can’t be sure what the array contains or how many values it has. The user of the function always needs to go and look at exactly what the function is doing to be sure. Bad luck if it’s some 1000 line monstrosity with ten levels of indentation.
When you’re sure you know what the function is giving you, you may not want all of the values in the array it’s returning. In that case, your options are:
- Leave unused variables in the local scope, which your static analyser will rightly complain about.
- Refer to particular values by their index (e.g.
$bar = severalThings()[1]), which is unclear and will also prevent analysers from picking up various problems they otherwise would have known about. - Do something like
list($foo,,$bar) = severalThings(). Also fairly horrible.
This doesn’t just cause problems for users of the function. Once you’ve got
client code using list on the return values of a function, it’s difficult to
ever change the number or ordering of elements. As mentioned above, code
analysis tools have no idea what’s going on with list, so automated
refactorings are out.
There is one clear solution to all of this: don’t return an array, return an
instance of a class. Anywhere list is used is begging for a class.
When list is used, we’ve got a situation where we need x, y and z values. A
class or interface is the perfect way to achieve that in a safe, clear and
maintainable way. In PHP 5, a doc block can indicate what interface the function
is going to return, and in PHP 7 we can guarantee it with a return type.
Returning an instance of a class or interface also makes the code easier to change in future. You don’t need to add bloat to the function if more logic is required, as it can now be encapsulated in the class, which has all the advantages you’d expect when dealing with an object:
- It’s easy to add more functionality to the return value in an understandable way.
- Existing clients don’t need to change if the returned object has a new method on it.
- Test code can be more expressive and better document the functionality.
- Static analysers understand the code and can help you find problems while you’re still writing it.
- In PHP 7 you can use anonymous classes that implement the expected return interface, making this even more flexible.
In short, classes are better than list().