Error Handling

By bootstrapping the library no custom error handling is performed, and this is entirely left at your discretion. If you choose to use one of the in-built Environments rather than define your own, then a customised error handling system is setup on creation.

  1. <?php
  2. require 'path/to/lib/bootstrap.php';
  3. // default error handling
  4. $env = new T_Environment_Http;
  5. // error handling environment has been customised
  6. ?>

Handling Exceptions

Uncaught exceptions normally reach a default global exception handler which treats them as fatal errors. In the customised error handling environment, uncaught exceptions are handled instead by an instance of T_Exception_Handler. This class acts as simple proxy to a chain of exception handlers: any exception that bubbles up to the global scope is passed down the chain by T_Exception_Handler until it finds a sub handler that recognises and can handle it. If it is not handled by any helpers in the chain the system acts like the default PHP exception handler and displays the exception if php.ini display_errors is on, and then quits with a fatal error.

The value of this system is that you can define your own global exception handlers, and have a chance to intercept and react to the global exception before the script quits with a fatal error. It is important to note that you cannot prevent script termination after the handler has completed (it is not possible to recover normal code exception since the exception is uncaught), but you do have a chance to for example log the error, present a 'user friendly' error output page, etc.

For example, if we wanted to setup our environment to log all global exceptions to the system error log and then present an error page to the user:

  1. <?php
  2. class Error_Log implements T_Exception_Handler_Action {
  3. function handle(Exception $e) {
  4. syslog(LOG_ERR,$e->getMessage());
  5. return false; // continue down handler chain
  6. }
  7. }
  8. class Error_Display implements T_Exception_Handler_Action {
  9. function handle(Exception $e) {
  10. while (ob_get_level()) ob_end_clean(); // delete buffers
  11. echo 'User friendly error message (probably HTML)';
  12. return true; // make this the final handler
  13. }
  14. }
  16. $env = new T_Environment_Http;
  17. $env->like('T_Exception_Handler')
  18. ->append(new Error_Display) // can either append
  19. ->prepend(new Error_Log); // or prepend to chain
  20. ?>

Handling Errors

The customised error handler will handle only those errors that are equal to or above the current php.ini (or runtime set) error_reporting level, so the @ operator and error_reporting function will work as expected. The handler will convert such errors into an ErrorException and then pass them into the T_Exception_Handler chain. If they are not handled by the chain (i.e. by a sub-handler returning true), the handler will throw the error in the hope that it will be caught by the client code.

  1. <?php
  2. $env = new T_Environment_Http;
  3. try {
  4. trigger_error('msg',E_USER_WARNING);
  5. // never gets here
  6. } catch (Exception $e) {
  7. // error -> ErrorException and is caught here
  8. }
  9. ?>

It is important to note that although this gives you more powerful in-code error handling (as try-catch blocks can be used for both exceptions and standard PHP errors), it does mean that an error that is not handled by the chain is "upgraded" to a global uncaught exception and is thus considered by PHP to be fatal.

Since the error is converted to an exception before it is handled, the error handlers you define are used for both Exceptions and standard PHP errors. For example reusing the Error_Log and Error_Display classes we can define a chain that logs *all* errors and uncaught exceptions, suppresses non-fatal PHP errors or otherwise displays a friendly error message for fatal PHP errors/exceptions:

  1. <?php
  2. class Error_Suppress implements T_Exception_Handler_Action {
  3. function handle(Exception $e) {
  4. $fatal = E_ERROR|E_USER_ERROR|E_RECOVERABLE_ERROR;
  5. return ($e instanceof ErrorException) &&
  6. !($e->getSeverity()&$fatal);
  7. }
  8. }
  10. $env = new T_Environment_Http;
  11. $env->like('T_Exception_Handler')
  12. ->append(new Error_Log)
  13. ->append(new Error_Suppress)
  14. ->append(new Error_Display);
  15. ?>

In-Built Exception Handlers

For convenience, the library has already defined a few in-built exception sub-handlers that you can use straight away in your code:

  • T_Exception_Handler_Debug implements the constructor-set error reporting level and displays any error then stops the script execution.
  • T_Exception_Handler_Terminal implements the constructor-set error reporting level, then writes any error messages to the error stream before exiting with the specified error code.
  1. <?php
  2. // e.g. set up a debug HTTP environment
  3. $env = new T_Environment_Http;
  4. $env->like('T_Exception_Handler')
  5. ->append(new T_Exception_Handler_Debug(E_ALL|E_STRICT));
  7. // e.g. set a terminal environment
  8. $env = new T_Environment_Terminal;
  9. $env->like('T_Exception_Handler')
  10. ->append(new T_Exception_Handler_Terminal(E_ALL^E_NOTICE));
  11. ?>

There are currently no defined production error sub-handlers, although some are planned shortly and examples to form a basis for your own have already been covered.

How-Tos

Want to see the code?

If you want to poke around the code itself, you can use git to grab yourself a copy.

Reference

If you're already familar with the codebase but simply want to look something up, best to head over to the code reference.

Had enough of an introduction?