Error 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 errorHandler function, that is intended to do global error handling. This function is used to catch and handle errors at a central place. For this reason, it uses a ErrorHandler component, that can be configured within the registry. The error handler itself is then responsible for the handling of the current error.

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

2. Configuration

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

The definition of a custom error handler looks as follows:

PHP-Code
Registry::register( 'apf::core', 'ErrorHandler', new ErrorHandlerDefinition( 'my::errorhandler::namespace', 'MyErrorHandler' ) );

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

If the registry offset does not contain a valid definition, the errors are displayed in text mode. You can identify the fallback mode by the prefix
APF-Template
APF catchable error:
In this cases, the definition or the implementation of the error handler class must be checked.
In order to deactivate the ErrorHandler, initalize the registry offset with null. Please note, that this is not recommended because the APF then directly prints the error information to screen. These may include sensible data!

3. Enhancement

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

PHP-Code
class AbstractErrorHandler extends APFObject { public function handleError($errorNumber,$errorMessage,$errorFile,$errorLine){ } }

If an error occurs, the handleError is applied the following parameters:

  • error number
  • error message
  • filename where the error occurs
  • line where the error occurs

Due to the fact, that the error 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 error 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 error handling mechanism can be used by calling the PHP function

PHP-Code
trigger_error();

Details on the usage of the function can be taken from the online documentation under http://php.net/trigger_error.

5. Further ErrorHandler

The 1.13 release ships two new error handler implementations for production use. Live systems are very sensible, hence the must secured best way. To guarantee security with data collected on error, the ProductionErrorHandler and ConfigurableErrorHandler are both implemented to hide data from potential attacker.

5.1. ProductionErrorHandler

In case an error occurs, the ProductionErrorHandler appends information on the error to the log file and then redirects to a pre-configured site. This hides error data from potential hackers.

The configuration can be done after pagecontroller.php inclusion as follows:

PHP-Code
Registry::register( 'apf::core', 'ErrorHandler', new ErrorHandlerDefinition( 'core::errorhandler', 'ProductionErrorHandler' ) ); Registry::register( 'apf::core::errorhandler', 'ProductionErrorRedirectUrl', '/pages/global-error' );

In case the ProductionErrorRedirectUrl directive is not set, the error handler redirects to "/".

5.2. ConfigurableErrorHandler

The ConfigurableErrorHandler enables you to handle errors concerning their error level. For this reason, you can define the threshold error level. Below this level, the handler ignores the error, above the threshold it handles the error as you know from the DefaultErrorHandler.

The configuration can be done after pagecontroller.php inclusion as follows:

PHP-Code
Registry::register( 'apf::core', 'ErrorHandler', new ErrorHandlerDefinition( 'core::errorhandler', 'ConfigurableErrorHandler' ) ); Registry::register( 'apf::core::errorhandler', 'ConfigurableErrorReportingLevel', E_ALL ^ E_NOTICE );

Using the configuration shown in the code box above all errors are handled by the error handler except E_NOTICE errors. 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.