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.

Error handling

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

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.

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.

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.

Configuration

See config-dist.php 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.

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.