Apache Zeta Components - high quality PHP components

• Tutorial
• API

eZ Components - Execution

Introduction

When there is a problem with your web application, you do not want your visitors to 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 allows you to show more user-friendly error messages.

Class overview

The Execution packages provides the ezcExecution class. This class provides the full interface to catch "fatal" errors. The component also provides the ezcExecutionErrorHandler interface for implementation by error handlers. A basic error handler is supplied through the ezcExecutionBasicErrorHandler class.

Usage

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

Before your application quits with exit() or die(), you need to signal to the ezcExecution environment that your application exited properly. Without this signal, the handlers assume that your application has ended unsuspectedly. The onError() method of the class you specified with the init() method will thus be called.

This is a basic example:

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

In line 4, we initialize the environment and in line 6, we signal to the environment that we have a clean exit. Otherwise, the script would have displayed the following message:

This is simply the default message and can be customized. To do so, 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 message:

1. <?php
2. require_once 'tutorial_autoload.php';
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.         }
17.         echo "This application did not succesfully finish its request. " .
18.             "The reason was:\n$message\n\n";
19.     }
20. }
22. ezcExecution::init( 'MyExecutionHandler' );
24. throw new Exception( "Throwing an exception that will not be caught." );
26. ezcExecution::cleanExit();
27. ?>

In lines 4-20, we declare our handler class MyExecutionHandler, which implements the ezcExecutionErrorHandler interface. Using the onError method, on line 8 we check whether the error was caused by an uncaught exception. In that case, we insert the exception's message into the $message variable. Otherwise, we assign a static value to $message. $message is then displayed in lines 17 and 18.

When you run the above script, the following warning is displayed:

This is due to line 24, where we throw an uncaught exception. If lines 24 and 26 are commented out, the result will instead be as follows:

More information

For more information, see the ezcExecution API documentation.