php return or reference?

Question

I have got a couple of functions that manipulate data in an array, for example unset_data() you pass it the value and an unlimited amount of string args like:

unset_data( $my_array, "firstname", "password" );

and it can handle multi-dimentional arrays etc, quite simple.

But should this function use a reference to the array and change it directly?

Or should i return the new array with the values unset.

I can never decide whether a function should use reference or not,

Is there like, specific cases or examples when and when to not use them??

Thanks

Answer 1

Generally speaking, it's better to return by value instead of taking a reference because:

1. It's the most common usage pattern (there's one less thing to keep in mind about this particular function)
2. You can create call chains freely, e.g. you can write array_filter(unset_data(...))
3. Generally speaking, code without side effects (I 'm calling the mutation of an argument in a manner visible to the caller a side effect) is easier to reason about

Most of the time, these advantages come at the cost of using up additional memory. Unless you have good reason (or better yet, proof) to believe that the additional memory consumption is going to be an issue, my advice is to just return the mutated value.

Answer 2

I'd ask myself what the expected use case of the function is. Does the typical use case involve keeping the original data intact and deriving new data from it, or is the explicit use case of this function to modify data in place?

Say md5 would modify data in place, that would be pretty inconvenient, since I usually want to keep the original data intact. So I'd always have to do this:

$hash = $data;
md5($hash);

instead of:

$hash = md5($data);

That's pretty ugly code, forced on you by the API of the function.

For unset though, I don't think the typical use case is for deriving new data:

$arr = unset($arr['foo']);

That seems pretty clunky as well as possibly a performance hit.

Answer 3

I feel that there is not a general you should/shouldn't answer to this question - it depends entirely on the usage case.

My personal feeling is leaning towards passing by reference, to keep it's behaviour more in line with the native unset(), but if you are likely to end up regularly having to make copies of the array before you call the function, then go with a return value. Another advantage of the by reference approach is that you can return some other information as well as achieving modification of the array - for example, you could return an integer describing how many values were removed from the array based on the arguments.

I don't think there is a solid argument for "best practice" with either option here, so the short answer would be:

Do whatever you are most comfortable with and whatever allows you to write the most concise, readable and self-documenting code.