Path

ez components / documentation / api reference / latest / execution


eZ Components latest

Execution

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

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';
  3. ezcExecution::init( 'ezcExecutionBasicErrorHandler' );
  4. ezcExecution::cleanExit();
  5. ?>

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 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!

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

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 application did not succesfully finish its request. The reason was:
Throwing an exception that will not be caught.

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:

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.

Last updated: Mon, 21 Dec 2009