Error handling

Please note that the documentation on this page refers to releases >= 1.15. For older releases, please see Error handling.

1. Introduction

The APF brings it's own global error handling mechanism. This features is built on top of PHP's default error handling and displays a nice error page including all parameters of the error as well as a stack trace to ease error analysis.

The architecture of the APF error handling is based on a central entry point (GlobalErrorHandler) that takes the current error and passes it to the registered ErrorHandler. The interface ErrorHandler brings multiple standard implementations (see below) and can be used to create your custom error handler that fit's your specific requirements.

2. Configuration

2.1. Custom error handler

The GlobalErrorHandler is activated by default and the DefaultErrorHandler is registered to handle upcoming errors.

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

PHP-Code

import('my::project', 'CustomErrorHandler');
GlobalErrorHandler::registerErrorHandler(new CustomErrorHandler());

If necessary, you may pass any information to the instance of your custom ErrorHandler (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 GlobalErrorHandler after inclusion of the pagecontroller.php:

PHP-Code

// deactivation of the APF error handling
GlobalErrorHandler::disable();

// reactivation of the APF error handling
GlobalErrorHandler::enable();

3. Implementation of an error handler

To introduce your custom error management the interface ErrorHandler must be implemented to register it with the GlobalErrorHandler. The interface defines the following method:

PHP-Code

interface ErrorHandler {

   public function handleError(
      $errorNumber,
      $errorMessage,
      $errorFile,
      $errorLine,
      array $errorContext);

}

In case an error occurs, the handleError() method is passed the following parameters:

Error number
Error message
File the error occured in
Line the error occured at
Variable scope during the error

Since the error handling is done within a class (e.g. DefaultErrorHandler) 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 CustomErrorHandler implements ErrorHandler {

   private $context;

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

   public function handleError($errorNumber, $errorMessage, $errorFile, $errorLine, array $errorContext) {
      ...
   }

}

GlobalErrorHandler::registerErrorHandler(new CustomErrorHandler('foo'));

You may use the DefaultErrorHandler, ConfigurableErrorHandler, and ProductionErrorHandler as a basis for the implementation of your custom ErrorHandler.

4. Usage

The APF global error handling mechanism can be triggered by adding PHP's

PHP-Code

trigger_error();

function to your sources. Details can be gathered from the online documentation under http://php.net/trigger_error.

5. Shipped error handlers

The APF brings two more ErrorHandler implementations that are recommended for production environments. It is very important to hide information about your production environment from potential hackers. For this reason, the ProductionErrorHandler and ConfigurableErrorHandler are built to hide the error data from attackers.

5.1. ProductionErrorHandler

In case an error occurs the ProductionErrorHandler 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 of this error handler can be done within the bootstrap file after inclusion of the pagecontroller.php:

PHP-Code

import('core::errorhandler', 'ProductionErrorHandler');
GlobalErrorHandler::registerErrorHandler(
   new ProductionErrorHandler('/pages/global-error')
);

The constructor argument takes the url the visitor is redirected to in case of errors.

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

5.2. ConfigurableErrorHandler

The ConfigurableErrorHandler enables you to ignore errors below a certain error level. For this reason, the constructor takes the error level that defines the threshold. Below this value, the ErrorHandler will ignore the error. Above it, it acts as the DefaultErrorHandler.

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

PHP-Code

import('core::errorhandler', 'ConfigurableErrorHandler');
GlobalErrorHandler::registerErrorHandler(
   new ConfigurableErrorHandler(E_ALL ^ E_NOTICE)
);

Having a look at the above configuration all errors except E_NOTICE are handled. Details on the configuration of error levels can be taken from the PHP documentation.

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.

Error handling

Comments

QUICKNAVI