Exception handling

Please note that the documentation on this page refers to releases including 1.14. For newer releases, please see Error handling.

1. Introduction

The framework features the exceptionHandler function, that is intended to do global exception handling. This function is used to catch and handle uncaught exceptions at a central place. For this reason, it uses an ExceptionHandler component, that can be configured within the registry. The exception handler itself is then responsible for the handling of the current exception. This mechanism is similar to the integrated Error handling.

The preconfigured APF exception handler saves the exception message into a log file and displays the nice exception screen including the stacktrace. Details can be taken from the API documentation of the DefaultExceptionHandler class.

2. Configuration

To replace the preconfigured DefaultExceptionHandler with an own class, the registry offset ExceptionHandler within the apf::core namespace must be filled with the desired ExceptionHandlerDefinition instance. The configuration of the exception handling component must be placed in the bootstrap file directly after the pagecontroller.php is included.

The definition of a custom exception handler looks as follows:

PHP-Code

Registry::register(
   'apf::core',
   'ExceptionHandler',
   new ExceptionHandlerDefinition(
      'my::exceptionhandler::namespace',
      'MyExceptionHandler'
   )
);

As you can take from the example, the desired ExceptionHandler is referenced by it's namespace and it's class name.

If the registry offset does not contain a valid definition, the exceptions are displayed in text mode. You can identify the fallback mode by the prefix

APF-Template

APF catchable exception:

In this cases, the definition or the implementation of the exception handler class must be checked.

In order to deactivate the ExceptionHandler, initilize the registry offset with null.

3. Enhancement

To introduce a custom exception handling, you must implement the AbstractExceptionHandler. This class defines the following interface:

PHP-Code

abstract class AbstractExceptionHandler extends APFObject {

   public function handleException($exception){
   }

}

If an error occurs, the handleException is applied the current exception object as an argument. Due to the fact, that the exception handling is done in an page controller independent class, that is not created by the service manager, the current Context and the current Language are not available!

If these information are important for the exception handling, the must be obtained from information containers available within an application or module (e.g. application model class). The environment param is available via the registry as mentioned in the corresponding documentation chapter.

4. Usage

The global exception handling mechanism can be used by placing the following PHP code within your application:

PHP-Code

throw new Exception('My application exception');

Please note, that the global exception handler only is invoked, when the current exception is not caught by a try-catch block!

Details on the usage of exceptions can be taken from the online documentation under

http://php.net/exception and http://php.net/exceptions.

5. Production ExceptionHandler

In parallel to to the ProductionErrorHandler the APF ships an ExceptionHandler for production environments since 1.13.

After including the pagecontroller.php the ProductionExceptionHandler can be activated as follows:

PHP-Code

Registry::register(
   'apf::core',
   'ExceptionHandler',
   new ExceptionHandlerDefinition(
      'core::exceptionhandler',
      'ProductionExceptionHandler'
   )
);
Registry::register(
   'apf::core::exceptionhandler',
   'ProductionExceptionRedirectUrl',
   '/pages/global-error'
);

In case the registry directive ProductionExceptionRedirectUrl is not set the ExceptionHandler redirects to "/".

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.

There are no comments belonging to this article.