Quick links: Content - sections - sub sections

The classes of the framework can generate errors in two different ways, with:

  • a trigger_error (PHP error)
  • an exception

A PHP error is generated in the case of a technical error due to a programing default. It is then the job of the developer to correct the error.

An exception is generated in the case of an error that can occur in an unpredictable way during the execution of an action. For example, an error when it is impossible to connect to a database or a "functional", "business" error.

Error handlers setup

Whatever the error comes from, we get it through an error handler (except for catched exceptions). There is an error handler for PHP errors and another for the exceptions.

Since Jelix 1.3, error handlers use jLog to store the error somewhere. By default, all errors (and warnings) are stored into a var/log/errors.log file.

You can change this behavior. You can also log all notices and other php errors, you can send messages to a syslog, etc. See the chapter on jLog to know how to configure it.

Note: all options in the [error_handling] (except messageLogFormat and errorMessage) existing for Jelix 1.2 and lower, are not used anymore since Jelix 1.3. They are deprecated.

The message format

The error message stored in files, syslog or mail, contains the error message itself, the stack trace and other useful informations. You can configure what should be store exactly. In the section [error_handling] of the configuration, you have an option messageLogFormat specifing the format of the message. This format supports some special keywords %date%, %ip%, %typeerror%, %code%, %msg%, %url%, %file%, %line%, %http_error%, \t and \n.

The error page

Since Jelix 1.3, details of error messages are never displayed in the browser (except in the debug bar if you activate it). When an error occured, Jelix displays an error page with the HTTP code 500.

By default, it shows the page stored in lib/jelix/core/response/error.en_US.php. You can provide your own page by copying this file into the yourapp/responses/ directory. Modify then this page to customize it with your own design.

Notice that error.en_US.php is a simple php script. You can write any PHP instructions. However, don't call any Jelix objects. The occured error may not appear in a "safe" context (some object may not be present, configured etc). And don't try to display the true error, for security reasons and for better usability. In fact, this page should be almost a static page. Just keep existing echo instructions.

Variables $HEADTOP, $HEADBOTTOM and $BODYTOP are not used for the moment (it is just to be compatible with static pages returned by jResponseBasicHtml). $BODYBOTTOM contains the error message, without details. A variable $BASEPATH is available, containing the base path of the application, for stylesheets etc. However, this variable may be empty in some case, depending of the origin of the error (an error appearing before or during the load of the configuration).

The error page may not be used in some case:

  • when there are fatal PHP errors
  • when an error occured during the initialization of the configuration file
  • when the browser doesn't accept html

In this last case, Jelix returns a simple text content. This text content can be configured into the option errorMessage inside the [error_handling] section of the configuration.

Errors code

Each error message is localized in the properties files and each error should have a number. This number is indicated in the properties files of the localized messages, this way:

 key.string = (error_code)error message

In the end, the error message won't be with the error code. And this one will be extracted

Here are the error codes fields

0-99 general errors
100-199 core errors
200-299 locale errors
300-399 templates errors
400-499 database errors
500-599 dao errors
600-699 authentication errors
700-799 rights errors
800-899 jforms errors
> 5000 user errors

If you generate errors for your own use, their code must be greater than 5000.