Status: Gyro-PHP Error Handling

One of the many epic discussions in software development is the question of exceptions versus return values. I’m personally more into the return values camp, and so is Gyro-PHP, although it uses a special error class rather then a simple TRUE or FALSE.

This class is called Status.

Exceptions vs. Return Value

Most developers prefer exceptions over return values, and most of them for very good reasons. If you ever had to cope with C-style error handling - like found in the Windows API, for example -, you certainly will honor exceptions for

Rich expression: The kind of error is expressed through an exception’s type, like OutOfRangeException. At the same time, an exception can carry a detailed, understandable error message, like “Your vote must be between 0 and 100 percent”.
Return value: Exceptions don’t eat up your return values, which often makes function declaration more clearly.
Bubbling: Exceptions allow code to just ignore them, and leave handling them to calling code.

Using exceptions for the exceptional

Bubbling comes in handy if something really, really bad happends deep down in the code - like a required module could not be loaded, or a database connect fails. Nobody expects this to happen. Of course, everybody knows this possibly could happen - but also everybody knowns that airplanes crash from time to time, without worrying too much when actually using one.

In case of the unexpected, there’s usually nothing else to do but to shut down gracefully. And that’s what Gyro-PHP does. If something really important fails, it will raise an exception. This will get catched quite on the top, in index.php, and a HTTP status code of 503 - Service unavailable will be send. This tells the client that something unexpected has happen, but that it also will get fixed soon.

Dealing with the expected

However, most errors are expected ones: Inserting or updating fails, because the user did not give all required data. A HTTP requests times out. You name it.

The calling code usually should know what to do in such a case, but unfortunately exceptions make immediate handling - well - noisy. Compare this two snippets of code:

<?php
function foo() {
  $success = do_a();
  if ($success) {
    do_b();
  } else {
    do_c();
  }
  do_d();
  return $success;
}

Using exceptions, this code would look like this:

<?php
function foo() {
  $ex = false;
  try {
    do_a();
  }
  catch (Exception $ex) {
    do_c();
  }
  if ($ex === false) {
    do_b();
  }
  do_d();
  if ($ex) {
    throw $ex;
  }
}

Obvioulsy, the catch misses an else, that’s why it must be coded. Things will become even worse, if you want to catch exceptions not only of one function, but many.

Status - the comfy chair of error handling

As said before, Gyro-PHP uses a special class called Status to indicate errors. Status is a combination of a boolean indicating error or success, and an array of strings representing (user friendly) error messages. Since Status is a class, you may extend it to express special errors, like you do with exceptions. The class Message extends Status to allow passing success messages.

By default Status has a state of “success”. But as soon as you pass it a message, it turns into an error. Messages can be passed in the constructor, or using the function append().

<?php
$err = new Status();
var_dump($err->is_ok()); // Bool: TRUE
var_dump($err->is_error()); // Bool: FALSE

$err = new Status('Oops!');
var_dump($err->is_ok()); // Bool: FALSE
var_dump($err->is_error()); // Bool: TRUE

$err = new Status();
$err->append('Oops!')
var_dump($err->is_ok()); // Bool: FALSE
var_dump($err->is_error()); // Bool: TRUE

You may append as many message as you like. You may also merge() another Status instance:

<?php
$first = new Status(); // is OK!
$second = new Status('Oops!'); // is ERROR!
$second->append('Did it again...')
var_dump($second->get_messages()); // Array ('Oops!', 'Did it again...')

$first->merge($second);
var_dump($first->is_error()); // Bool: TRUE
var_dump($first->get_messages()); // Array ('Oops!', 'Did it again...')

Rewriting above example using Status would look like this:

<?php
function foo() {
  $err = do_a();
  if ($err->is_ok()) {
    $err->merge(do_b());
  } else {
    $err->merge(do_c());
  }
  $err->merge(do_d());
  return $err;
}

Being able to collect errors from sub functions and return them as a whole makes working with return values much easier, since it allows some easy kind of bubbling.

I personally use classes similar to Gyro-PHP’s Status in all my projects, may it be PHP, C++ or C#, for years, and I really can’t live without it any more. Hope you will enjoy working with it, too!