xPDO.log
Last updated Apr 20th, 2021 | Page history | Improve this page | Report an issue
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$306 per month—let's make that $500!
Learn morexPDO::log¶
Log a message with details about where and when an event occurs.
Syntax¶
API Docs: https://api.modx.com/revolution/2.2/db_core_xpdo_xpdo.class.html#\xPDO::log()
$xpdo->log($level, $msg, $target= '', $def= '', $file= '', $line= '');
-
$level
(integer) The verbosity level of the logged message. See Verbosity Constants below -
$msg
(string) The message to log. -
$target
(mixed) The logging target. If a string, this should be FILE, HTML, or ECHO. If an array, see examples below. -
$def
(string) The name of a defining structure (such as a class) to help identify the log event source. -
$file
(string) A filename in which the log event occurred. Usually you would use the __FILE__ constant. -
$line
(string) A line number to help locate the source of the event. Usually you would use the __LINE__ constant
void log (integer $level, string $msg, [string $target = ''], [string $def = ''], [string $file = ''], [string $line = ''])
Log Levels¶
In many cases, you can use the MODX equivalent constants for log levels.
What gets printed is controlled by the log_level
System Setting. You can override this at runtime using the setLogLevel
method.
Examples¶
Simple¶
Simple log message, will write to the default log file (e.g. core/cache/logs/error.log
):
$xpdo->log(xPDO::LOG_LEVEL_ERROR, '[Mobile Detect] An error occurred.');
In the logs, this would appear like this:
[2013-09-15 14:21:25] (ERROR @ /index.php) [Mobile Detect] An error occurred.
Specify the Snippet¶
Because MODX application ultimately runs via the index.php file, it can be helpful to add some extra information:
$xpdo->log(xPDO::LOG_LEVEL_ERROR, 'An error occurred.', '', 'MySnippet');
[2013-09-15 14:22:48] (ERROR in MySnippet @ /index.php) An error occurred
Specify File and Line¶
Remember that ultimately, all MODX Snippets and Plugins run from cached files, so the source file listed will be the cached file.
$xpdo->log(xPDO::LOG_LEVEL_ERROR, 'This is my error message...', '', 'MySnippet', __FILE__, __LINE__);
[2013-09-15 14:48:02] (ERROR in MySnippet @ /path/to/core/cache/includes/elements/modsnippet/28.include.cache.php : 7) This is my error message...
Custom Log File¶
You may wish to send errors to a destination other than the default MODX error log. To accomplish this, you must pass an array to the $target
argument. You must verbosely specify 'FILE' as the target, otherwise, the message will be echoed back to the page.
$xpdo->log(xPDO::LOG_LEVEL_ERROR, 'Error for my custom log file', array(
'target' => 'FILE',
'options' => array(
'filename' => 'custom.log'
)
));
By default, the path for log files is core/cache/logs/
so in this example, we find our log message inside the custom.log
file:
[2013-09-15 15:01:07] (ERROR @ /index.php) Error for my custom log file
If desired, you may also specify the path via the filepath
argument.
Because this is a bit verbose, you may find it cleaner to define your logging target once then reference the array:
$log_target = array(
'target'=>'FILE',
'options' => array(
'filename'=>'my_custom.log'
)
);
$xpdo->log(xPDO::LOG_LEVEL_ERROR, 'My Error...',$log_target);
$xpdo->log(xPDO::LOG_LEVEL_ERROR, 'Some other error...',$log_target);
Debugging¶
You can change the level of the logged message by adjusting the first parameter. E.g. to log a debug message:
$xpdo->log(xPDO::LOG_LEVEL_DEBUG,'This is a debugging statement.');
Custom Use in Snippets¶
It can be really handy to increase logging verbosity for a single Snippet or plugin. To accomplish this, use the setLogLevel()
function. You can use this to override the global value of the log_level System Setting:
// Call your snippet like this: [[mySnippet? &log_level=`4`]]
// Override global log_level value
$log_level = $modx->getOption('log_level', $scriptProperties, $modx->getOption('log_level'));
$modx->setLogLevel($log_level);
Verbosity Constants¶
xPDO Constant | MODX Constant | Value |
---|---|---|
xPDO::LOG_LEVEL_FATAL | MODX_LOG_LEVEL_FATAL | 0 |
xPDO::LOG_LEVEL_ERROR | MODX_LOG_LEVEL_ERROR | 1 |
xPDO::LOG_LEVEL_WARN | MODX_LOG_LEVEL_WARN | 2 |
xPDO::LOG_LEVEL_INFO | MODX_LOG_LEVEL_INFO | 3 |
xPDO::LOG_LEVEL_DEBUG | MODX_LOG_LEVEL_DEBUG | 4 |
See Also¶
- log_level System Setting
- log_target System Setting
- xPDO
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$306 per month—let's make that $500!
Learn more