How to handle type checking boilerplate in PHP

Question

I'm writing a utility function to handle arrays. For the sake of avoiding complexity let's say it's a simple handle to allow shorthand array insertion into a function:

function array_insert($original_arr,$key,$val){
    $original_arr[$key]=$val;
    return $original_arr;
}

With the use case being e.g.

validate_input(array_insert($_GET,'extra-key','val'));

Now let's say we could have the issue that $_GET might not be an array. Or say we're taking input from an external call; where does the responsibility lie in checking that the first parameter is an array?

If this formed the start of a complex stack of processing we could do:

if (is_array($our_data)){
    do_something($our_data);
    do_something_else(array_insert($our_data,'key','val'));
}

This doesn't have the effect of letting the calling scope know that do_something didn't happen though. So we could do:

if (!is_array($our_data)){
    throw new Exception('not an array');
}

Now anything using our method needs to be prepared to catch that, and depending on whether we actually care about the result we might need to catch it within our method.

We could simply get out of the utility function and return false which something else can check for:

function array_insert($original_arr,$key,$val){
    if (!is_array($our_data)){
        return []; // which is empty but expected, or return false.. or null...
    }
}

Then there's the lowest level:

function array_insert(Array $original_arr)

Which will trigger a PHP level exception if an array isn't passed.

So the question is; for a utility function how much responsibility do we take about use case? Do we cause a language exception with a TypeHint, do we fail silently, do we not bother to check and let the end user figure it out?

Update

Firstly people are noting that this is subjective - I agree, though there is likely to be an established best practice, e.g. one recommended by certification schemes or large companies in the PHP world.

Secondly a further question (prompted by the first answer) is if there's an established Exception class/class name for this kind of issue?

This is subjective, but it really depends on the _responsibility_ of the function itself. In PHP some built-in functions throw notices or warnings because of the way they operate, or the level of _responsibility_ they are trying to assume. The difference between `include` and `require` are an example of this. An `include` will warn you that a file doesn't exist, but a `require` will cause PHP to crash and burn if it doesn't exist. So, the answer to your question is: your function's error checking needs to be as critical as you deem it for the operation it is carrying out. — Crackertastic, Oct 08 '14 at 11:31
I think that's the problem I'm struggling with; like many developers I've come up with a range of utility functions over the years, and would now like to open source most of them. However this desire to make work public highlights the need for some level of consistency - so I guess before I rewrite things to be forceful or to be ignorant I'd like some advice on practice for "generic" functions. — M1ke, Oct 08 '14 at 11:33
For most methods I write I tend to use type-hints and other methods to validate data. I especially do this if I am writing a method that expects a specific instance type to get passed in. Error checking as a whole is a good thing, even for the smaller functions. If you are planning to open source some stuff, then it might be better if you are a little more strict with your code. In my opinion there is nothing wrong being forceful with any library you write. Throwing exceptions and using type-hints only forces you (and any third parties) to use your code _correctly_. — Crackertastic, Oct 08 '14 at 11:41

score 1 · Accepted Answer · answered Oct 08 '14 at 11:54

As was already mentioned in the comments, this is totally subjective, but personally:

I always use type hints for objects and arrays.
For functions operating on primitive types I throw InvalidArgumentException based on the value only if some values are invalid and it might not be obvious. For example a function calculating square root of a number could throw an exception when passed a negative.
In all other cases I use meaningful function / parameter names and assume if someone decides it's a good idea to pass a non-numeric string or an array to a function defined as doStuffWithNumbers($num1, $num2), it's his responsibility if bad things happen in the result.

Thanks; based on your second point I've amended the original question regarding Exception naming - are there standardised names one would use for this type of use case? — M1ke, Oct 08 '14 at 12:48
@M1ke Here's a list of predefined SPL Exceptions: http://php.net/manual/en/spl.exceptions.php — lafor, Oct 08 '14 at 12:52

How to handle type checking boilerplate in PHP

Update

1 Answers1