Error Handlers

4.4.1 Introduction

Included in Harmoni is the ErrorHandler class. Like the DebugHandler, it stores messages in a queue and outputs them when you tell it to. However, some errors are fatal, and some are not. Fatal errors are printed immediately, along with any other errors in the queue.

Two services are registered using the ErrorHandler: ErrorHandler and UserError. The former acts as a "system" error manager, handling mostly fatal errors or warnings that are produced by your program and must be fixed by either an administrator or the programmer. The latter is meant to keep track of errors created by an end user, such as entering a malformatted email in a form field. Like the Debug service, there are wrapper functions for both of the error services. They will be eplained at the end of this subchapter.

4.4.2 Throwing a new error

There are two ways, using the ErrorHandler object, to add new errors. Both are outlined in the example:

Example


$errHandler =& Services::getService("ErrorHandler"); // or, "UserError"

// now, throw a new error
$errHandler->addNewError("This is my error string!","category",false);
// or, make an Error object (you could use your own custom object)
$errHandler->addError(
    new Error("This is my error string!","category",false)
        );

Both of the above methods do exactly the same thing. The advantage of using the second would be to create your own custom Error classes, for example to output common text with only one changing parameter (like, new EmptyFieldError("myFieldName") would print "You forgot to enter required information for myFieldName.").

The arguments: 1 = the error string, 2 = a category (whatever you want), 3 = is the error fatal? (fatal errors stop program execution)

4.4.3 Wrapper functions throwError and userError

Provided are two error handler wrapper functions. Both work identically but on different services, mentioned above. throwError() will throw an error to the ErrorHandler Serivce, whereas userError() will throw to UserError.

Example


// throw an error to ErrorHandler
throwError( new Error("AAAAAAH! Something went very wrong! Aborting...","DB-API",true) );

// or to UserError
userError( new Error("You didn't enter your name in the form!","user",false) );

4.4.4 Printing Errors

There are a couple ways to print errors from an ErrorHandler. 1) You can use one of the provided: ErrorPrinterBasic or SimpleHTMLErrorPrinter printer classes, or 2) you can write your own printer following the interface found in harmoni/core/errorHandler/errorPrinter.interface.php. All ErrorPrinters would be used in the same fashion:

Example


$errHandler =& Services::getService("ErrorHandler"); // or, "UserError"

// now print the errors in HTML (or whatever)
$errHandler->printErrorsWithErrorPrinter( new ErrorPrinterBasic() );
// or, new SimpleHTMLErrorPrinter()

It's really that easy. You should take a look at the PHPDoc for the ErrorHandler and ErrorPrinterInterface for more detailed information.