Exception handling

1. Introduction

Similar to the Error handling the APF provides a global exception handling mechanism that catches exceptions that are not caught by the application. As you know from error handling mechanism displays a nice error page including all parameters of the exception as well as a stack trace to ease analysis.

The architecture of the APF exception handling is identical to the error handling and is managed from a central entry point (GlobalErrorHandler). This component takes the current exception and passes it to the registered ExceptionHandler. This procedure can be used to handle critical exceptions (e.g. connection loss towards a middle tier system) at one central point. Thus, the code of the dedicated functional can be kept clean.

There is one standard implementation based on the interface ExceptionHandler that can be used as a basis for custom implementations (see below).

2. Configuration

2.1. Custom exception handler

The GlobalExceptionHandler is activated by default and the DefaultExceptionHandler is registered to process the exceptions.

In order to replace the pre-configured state with your own exception handler, please add the following code to your bootstrap file after inclusion of the pagecontroller.php:

PHP-Code

import('my::project', 'CustomExceptionHandler');
GlobalExceptionHandler::registerExceptionHandler(new CustomExceptionHandler());

If necessary, you may pass any information to the instance of your custom ExceptionHandler (e.g. Context).

2.2. Activation and deactivation

In case the APF mechanism should be deactivated for some reason or you intend to re-activate it, you can use the GlobalExceptionHandler after inclusion of the pagecontroller.php:

PHP-Code

// deactivation of the APF exception handling
GlobalExceptionHandler::disable();

// reactivation of the APF exception handling
GlobalExceptionHandler::enable();

3. Implementation of an exception handler

To introduce your custom exception management the interface ExceptionHandler must be implemented to register it with the GlobalExceptionHandler. The interface defines the following method:

PHP-Code

interface ExceptionHandler {

   public function handleException(Exception $exception);

}

In case an exception occurs, the handleException() method is passed the current exception.

Since the error handling is done within a class (e.g. DefaultExceptionHandler) that is not created with the ServiceManager Context and Language cannot be accessed as known from taglib classes or document controllers!

In case more information are needed to process the error event, you may pass any attribute to the constructor or to any getter method of the error handler instance. Sample:

PHP-Code

class CustomExceptionHandler implements ExceptionHandler {

   private $context;

   public function __construct($context) {
      $this->context = $context;
   }

   public function handleException(Exception $exception) {
      ...
   }

}

GlobalExceptionHandler::registerExceptionHandler(new CustomExceptionHandler('foo'));

You may use the DefaultErrorHandler and ProductionExceptionHandler as a basis for the implementation of your custom ExceptionHandler.

4. Usage

The global exception handling mechanism is invoked each time an exception is not caught by application code. This might by design or unexpectedly.

Unexpected exceptions mainly occur during development. For this reason the global exception handling mechanism displays a nice exception page with all necessary information to solve the issue.

Using the global exception handler for a conceptual reason, exceptions caught here are merely represent a situation that cannot be recovered by the application (e.g. connection loss to a middle tier system). For this situations, you can use the ProductionExceptionHandler to provide a dedicated error page for the website visitor.

In order to trigger the global exception handling mechanism, just add

PHP-Code

throw new Exception();

to your application code and do not catch it.

5. Shipped exception handlers

The APF brings the ProductionExceptionHandler as a further implementation to be used within production environments. It is very important to hide information about your production environment from potential hackers. For this reason, the ProductionExceptionHandler are built to hide the error data from attackers.

In case an exception occurs the ProductionExceptionHandler appends an entry to the global log file and redirects the user to the previously defined page. This prevents error detail data from being viewed from the outside.

The configuration can be done within the bootstrap file after inclusion of the pagecontroller.php:

PHP-Code

import('core::exceptionhandler', 'ProductionExceptionHandler');
Registry::register('apf::core::exceptionhandler', 'ProductionExceptionRedirectUrl', '/pages/global-error');
GlobalExceptionHandler::registerExceptionHandler(new ProductionExceptionHandler());

The registry key takes the url the visitor is redirected to in case of errors.

Please ensure, that the exception page does not trigger further errors. Otherwise, you may create a redirect loop that has not exit condition!

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.