PHP: Should a checking function throw an exception - php

Question

This doesn't necessarily only apply to PHP, but that's my area of concern.
I have been writing a few checking functions recently, that get some argument and then check its validity in various ways. Like, checkXmlString($xml) will check whether the given string contains a well-formed xml document, etc.
The question is, should those functions return a boolean, or throw exceptions and not return anything on success.
So
function checkAbc($arg) { if ($arg is invalid) return false; else return true; }
or rather
function checkAbc($arg) { if ($arg is invalid) throw new Exception(...); }

Answer 1

You could throw a InvalidArgumentException to check if arguments are incorrect but i think for your case if you are writing "checkers" they should return a boolean so you know not to continue operations, for example if the foobar.xml is actually a CSV file you wouldn't want to continue with your operation but you wouldn't want to catch an exeption either
<?php
class Checker {
function validXml($string)
{
if(!(bool)$string) throw new \InvalidArgumentException("Cannot pass empty string as argument", 1);
// Check
// Is valid XML ? Return True : return false
}
}
try {
if(new Checker->validXml($xmlString))
{
// Continue Operation
// return
}
// Notify User of invalidity
// return
} catch (\InvalidArgumentException $e) {
// Log args
//
}

Answer 2

According to almost all books written on subject and not least, according to logic, the name should be the biggest hint of what the function does. In that case, only the first option applies. As Bet Lamed said previously, a function called "check" is not supposed to throw exceptions, just to let you know if the check is ok or not.
If you want exceptions, you might want to rename it to DeserialisationToAbc() or TryParseAbc() or something similar.

Answer 3

The question is, should those functions return a boolean, or throw
exceptions and not return anything on success.
First identify If It is an exceptional situation than use exception .You case does not seems to be exceptional, It is just a condition , so treat it like a condition.If It was like It is correct but fails on certain situation, you may not identify well than you may consider using exception.
Visit these two links and learn more about exception
Exception Best Practices in PHP 5.3
A primer on PHP exceptions

Answer 4

This is of course a bit opinion based, but ask yourself, what do you expect from a function like checkEmail() ? The purpose of the method is to validate something, so you propably expect an answer to this question.
$isValid = checkEmail($arg);
I think most developers expect a bool as return value, it makes the code readable. Wrong values are expected, so one cannot say it is an exception if an invalid argument is passed. To return an error message as well i would use an out parameter:
function checkAbc($arg, &$errorMessage)
{
if ($arg is invalid)
{
$errorMessage = 'The argument is invalid because of...';
return false;
}
else
{
$errorMessage = '';
return true;
}
}

Answer 5

I'm really not quite sure which form is preferrable in general.
On the one hand, in case of an error, you want a useful message, so you end up with mixed returns (true/string), which is ugly, or returning an array (even uglier). An exception gives you that for free.
On the other hand, a function called check...() should not be expected to throw an exception, because finding out that "this is not a valid thingie" is nothing exceptional and not an error.
The third way would be to call it "throwIfFalse", but that's ugly too....
Hmm....
One possible solution:
interface Checker {
public function check();
public function getMessage();
}
class WhateverChecker implements Checker { ... }
class ClientOfChecker {
public function doStuff() {
$checker = new Checker();
if (! $checker->check() )
throw new Exception($checker->getMessage());
}
}
However, that seems incredibly verbose, and, may I say, Javaesque to me.

Answer 6

There is generally 2 types of function regarding your question:
Pure function that tests whether a condition holds.
Function that ensures a condition holds and alters control flow if it does not.
Different programming language may have different conventions about the naming of both types. Take C++ as an example, one common naming is CHECK_XXX for type 2 and IsXXX for type 1.
Here is an example taken from a tutorial of the google-log library:
CHECK(fp->Write(x) == 4) << "Write failed!";
CHECK_NE(1, 2) << ": The world must be ending!";
Another example is the maktaba utility library for Vimscript , where maktaba#value#IsXXX() is used to test whether the argument is of a certain type while maktaba#ensure#IsXXX() is used to ensure IsXXX holds and throws an exception otherwise.
function! TakeAString(name)
" Ensure argument type is String.
let name = maktaba#ensure#IsString(a:name)
endfunction
if maktaba#value#IsString(name)
" Branch if name is a String.
echo name
endif
So here is the point: choose the one that suits your need best and name the function according to the convention of the language. In terms of use cases of both, roughly, use the type 2 to check pre-condition like argument type and use the type 1 in conditional statements.