A module author will sooner or later want to log what the module is doing. Most helpful is logging when the module is not doing what it should do, though...
![[Note]](images/admonitions/note.png) | Note |
|---|---|
This is not intended to notify the end user of errors or tell them what happens. Have a look at the notification functions for this! | |
In the settings module, in the general section, the are a bunch of logging settings. The first one, 'enable_logging' is a systemwide on/off switch for logging. When it is enabled a 'log' link is placed next to 'help' in the mgw submenu. This link opens a window displaying all log data for the page you just requested.
There are also 'log level' settings for each module (except general, which always has all levels enabled). You can turn these all on/off independantly. If a level is off, all log calls for that level are discarded.
Only the admin user can change the logging settings. During normal use, it is probably a good idea to disable logging (disabled by default after setup) to reduce overhead.
You can always log messages with one simple function call. Those messages can have one of five logging levels: MGW_FATAL, MGW_ERROR, MGW_WARNING, MGW_NOTICE, MGW_INFO. Those are predefined constants you can use right away.
In appconfig the logging class is initiated and can be reached anywhere using $GLOBALS['log']. To log stuff, use the function $GLOBALS['log']->message(). It returns a boolean value to indicate the call result.
Example 21.2. Firing a log message.
$GLOBALS['log']->message(MGW_INFO, 'This is a info message.', __LINE__, __FILE__);
If you want to force logging even if a particular log level is turned off, you can specify a boolean as fifth parameter. If you set this to true, the message is logged forcibly. But: if logging is disabled generally, the message will be discarded regardless of this setting!
Finally you can specify another optional parameter (a string), to overwrite the module name associated with the message. Ususally this is taken from $myEnv, so you generally shouldn't need this.
Example 21.3. Firing an extended log message.
$GLOBALS['log']->message(MGW_NOTICE, 'Forced logging under a manually set module name.',
__LINE__, __FILE__, true, 'test');
Use those calls wherever you see fit, and try to distribute them logically throughout the code. The main purpose is tracking what the code really does to aid debugging, so you might want to log error messages, checkpoints reached, ...