Chapter: Configuring the error management
| ^ Development helper tools | Debugging and using jLog » |
− Table of content
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%, \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.
