Introduction

If there is a problem with your Web application you do not want that your visitors see "Fatal error" messages. Instead you want to be able to show them a more friendly page telling them what might be wrong, or what they should do when they encounter such an error.

Fatal errors and uncaught exceptions in PHP abort your script, but with this component you can add hooks to the shutdown system of PHP. This gives you the change to show a user-friendly message.

Class overview

The Execution packages provides the ezcExecution class. This class provides the full interface to set up the catching of "fatal" errors. The component also provides the ezcExecutionErrorHandler interface that error handlers should implement. A basic error handler is supplied through the ezcExecutionBasicErrorHandler class.

Usage

When starting your application you need to initialize the ezcExecution class by calling ezcExecution::init( $className ). The $className is the name of the class that implements your handler. In our first example we simply use the default provided handler ezcExecutionBasicErrorHandler. Calling the init() method sets up the environment and registers the necessary handlers with PHP.

Before you exit() or die() from your application you need to signal the ezcExecution environment that your application exitted properly. Without this signal the handlers assume that your application ended unsuspectedly. In that case they will call the onError() method of the class you specified in the init() method.

This example shows the most basic usage:

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. ezcExecution::init( 'ezcExecutionBasicErrorHandler' );
  5. 
  6. ezcExecution::cleanExit();
  7. ?>

In line 4 we initialize the environment and in line 6 we signal the environment that we have a clean exit. If we would not have done this, then the script would have displayed the following message:

This application stopped in an unclean way.  Please contact the maintainer
of this system and explain him that the system doesn't work properly at the
moment.

Have a nice day!

Of course this is just a default message and you most likely want to tune this to your needs. To do so you will have to create a new class that implements the ezcExecutionErrorHandler interface. You will only have to implement one method: onError(). In the next example we create such a class and implement a custom notice.

  1. <?php
  2. require_once 'tutorial_autoload.php';
  3. 
  4. class MyExecutionHandler implements ezcExecutionErrorHandler
  5. {
  6.     public static function onError( Exception $e = NULL )
  7.     {
  8.         if ( !is_null( $e ) )
  9.         {
 10.             $message = $e->getMessage();
 11.         }
 12.         else
 13.         {
 14.             $message = "Unclean Exit - ezcExecution::cleanExit() was not called.";
 15.         }
 16. 
 17.         echo "This application did not succesfully finish its request. " .
 18.             "The reason was:\n$message\n\n";
 19.     }
 20. }
 21. 
 22. ezcExecution::init( 'MyExecutionHandler' );
 23. 
 24. throw new Exception( "Throwing an exception that will not be caught." );
 25. 
 26. ezcExecution::cleanExit();
 27. ?>

In the lines 4-20 we declare our handler class "MyExecutionHandler" which implements the ezcExecutionErrorHandler interface. In it's only method (onError, line 6-19) we check on line 8 if the error was caused by an uncaught Exception. In that case we retrieve the exception's message into the $message variable. Otherwise we assign a static value to $message. The $message is the displayed in line 17 and 18.

When you run the above script, you will be presented with the following warning (as we threw an exception on line 24 which we didn't catch):

This application did not succesfully finish its request. The reason was:
Throwing an exception that will not be caught.

If you comment out line 24 and 26, the result will instead be:

This application did not succesfully finish its request. The reason was:
Unclean Exit - ezcExecution::cleanExit() was not called.

More Information

For more information, see the ezcExecution API documentation.