View source for Developer Area/Core Subsystems/Error Handling, Logging and Messages

This page details how the error/excpetion handling and logging works in Mahara. It also details how messages displayed to the user. This page is '''not''' about the system for messaging users through email etc.

<div id="section_1">

===Error handling===

This section describes error handling, '''not''' exceptions, which are described below.

<div id="section_2">

====Concepts====

Error handling is done with the help of two concepts: log '''levels''' and log '''targets'''.

A log level is reasonably straight forward - there are four levels of logging in the system, debug, info, warning and environment. Errors that occur in the system will occur at one of those four levels.

A log target is either the error log or the screen at this point, although targets such as email, emaildigest etc. are easily enough added. For each log level, you can configure the system to send the messages at that level to any combination of the log targets.

So, for example, you could send debug and info notices to the logs, warnings to the log and screen and environment errors nowhere. Different combinations will suit different installations, from development to a production site.

</div><div id="section_3">

====Types of Log Levels====

The debug, info and warning levels have a similar meaning to what you would expect - they are for messages in increasing importance (and presumably decreasing occurance). The "environment" level is for messages that are related to the sanity of the setup that Mahara is installed in - for example, register_globals being turned on. Developers will probably never need to use this level.

</div><div id="section_4">

====Backtraces====

You can configure which levels of logging generate backtraces in the config.php file. This allows you to choose which levels to receive more information about. Typically, you only want backtraces for warnings, but you can generate backtraces for all levels of errors if required.

</div><div id="section_5">

====Configuration====

See <tt>htdocs/lib/config-defaults.php</tt> for examples of how to configure logging.

====Triggering errors====

The following four functions are available for triggering errors:
* log_debug
* log_info
* log_warn
* log_environ

Each one takes three parameters:
* '''$message''': The message to log
* '''$escape''': Whether to HTML escape the message when it appears in an HTML context. By default, this is true. This allows messages to be logged that include HTML, if necessary. Not normally so useful for logging, but as the messaging system uses this and the underlying engine is the same, the support is available for this.
* '''$backtrace''': Whether this message should include a backtrace. By default this is true, but there may be cases where you wish to log a message and the backtrace won't be helpful, in which case you can set this to false.

====Notes====

PHP notices and warnings are changed to "warning" level messages and then are handled the same as the rest of the system.

</div></div><div id="section_8">

===Exceptions===

There is a default exception handler registered, if it catches anything it will end the script with a non-committal message to the user. Please try to catch exceptions that your code can deal with if possible, without catching the "Exception" class itself.

</div>
[[Category:Developer Area]]