Error Handling and Reporting

PRADO provides a complete error handling and reporting framework based on the PHP 5 exception mechanism.

Exception Classes

Errors occur in a PRADO application may be classified into three categories: those caused by PHP script parsing, those caused by wrong code (such as calling an undefined function, setting an unknown property), and those caused by improper use of the Web application by client users (such as attempting to access restricted pages). PRADO is unable to deal with the first category of errors because they cannot be caught in PHP code. PRADO provides an exception hierarchy to deal with the second and third categories.

All errors in PRADO applications are represented as exceptions. The base class for all PRADO exceptions is TException. It provides the message internationalization functionality to all system exceptions. An error message may be translated into different languages according to the user browser's language preference.

Exceptions raised due to improper usage of the PRADO framework inherit from TSystemException, which can be one of the following exception classes:

• TConfigurationException - improper configuration, such as error in application configuration, control templates, etc.
• TInvalidDataValueException - data value is incorrect or unexpected.
• TInvalidDataTypeException - data type is incorrect or unexpected.
• TInvalidDataFormatException - format of data is incorrect.
• TInvalidOperationException - invalid operation request.
• TPhpErrorException - catchable PHP errors, warnings, notices, etc.
• TSecurityException - errors related with security.
• TIOException - IO operation error, such as file open failure.
• TDBException - errors related with database operations.
• TNotSupportedException - errors caused by requesting for unsupported feature.
• THttpException - errors to be displayed to Web client users.

Errors due to improper usage of the Web application by client users inherit from TApplicationException.

Raising Exceptions

Raising exceptions in PRADO has no difference than raising a normal PHP exception. The only thing matters is to raise the right exception. In general, exceptions meant to be shown to application users should use THttpException, while exceptions shown to developers should use other exception classes.

Error Capturing and Reporting

Exceptions raised during the runtime of PRADO applications are captured by System.Exceptions.TErrorHandler module. Different output templates are used to display the captured exceptions. THttpException is assumed to contain error messages that are meant for application end users and thus uses a specific group of templates. For all other exceptions, a common template shown as follows is used for presenting the exceptions.

Customizing Error Display

Developers can customize the presentation of exception messages. By default, all error output templates are stored under framework/Exceptions/templates. The location can be changed by configuring TErrorHandler in application configuration,

<module id="error"
    class="TErrorHandler"
    ErrorTemplatePath="Application.ErrorTemplates" />

THttpException uses a set of templates that are differentiated according to different StatusCode property value of THttpException. StatusCode has the same meaning as the status code in HTTP protocol. For example, a status code equal to 404 means the requested URL is not found on the server. The StatusCode value is used to select which output template to use. The output template files use the following naming convention:

error<status code>-<language code>.html

where status code refers to the StatusCode property value of THttpException, and language code must be a valid language such as en, zh, fr, etc. When a THttpException is raised, PRADO will select an appropriate template for displaying the exception message. PRADO will first locate a template file whose name contains the status code and whose language is preferred by the client browser window. If such a template is not present, it will look for a template that has the same status code but without language code.

The naming convention for the template files used for all other exceptions is as follows,

exception-<language code>.html

Again, if the preferred language is not found, PRADO will try to use exception.html, instead.