In my previous article, we took a deep dive into the details of the MODX Error Log. One thing we didn't cover is how to log error message to your own log file in the traditional location or a different one. We'll see how to do that in this article.
Not the Best Way
One way to use a custom error log is to use FILE in the third argument to the log() method and change the error_log_filename and error_log_filepath System Settings. This is almost never a good idea. All it does is move the MODX Error Log to a new location, and I can't think of a valid reason for doing that.
Why Create a Custom Error Log?
When you want a custom error log, it's because you want to log some error messages somewhere else, not all of them. Maybe it's because your MODX error log is large and includes lots of error messages. If you're working on a plugin, a snippet, or a MODX extra, during development you might want to put the messages in another location that's guaranteed to contain only error messages from the code you're working on. If you like, you can use several different logs for different parts of your code or different files. The best way to do that is to send an array as the third argument to the log() method.
The $target Argument
As we learned in the previous article the Log Target goes in the third argument to the log() method ($target). This argument tells MODX where to put the message. If that argument is an array, MODX assumes that you're going to put the message somewhere other than the MODX Error Log at core/cache/logs/error.log.
The Array
There array you send as the third argument should always look like this:
array(
'target'=>'FILE',
'options' =>
array(
'filename'=>'my_custom.log'
)
)
You can use the code above in the third argument, but is makes your log() call fairly complex and difficult to read. A cleaner way is to make is to make the array a separate variable and send that variable as the third argument:
$target = array(
'target'=>'FILE',
'options' =>
array(
'filename'=>'my_custom.log'
)
);
$modx->log(modx::LOG_LEVEL_ERROR, 'MyMessage', $target);
Notice that in this case, the array has a semicolon (;) at the end, unlike the array used as an argument.
In the array, the FILE at the top tells MODX that the message is going to a file. In the options array, we send the filename of the custom file. Important: You must use options, and filename as the two keys here, otherwise MODX won't understand your code.
As written above, the custom file will be found in the core/cache/logs/ directory. This is not a bad place for it. It's the standard location for log files, and it will survive clearing the cache, either with the built-in Menu option ("Manage->Clear Cache") or the CashClear extra. It will not survive someone clearing the cache manually by deleting all files in the core/cache directory, unless the person avoids deleting the logs/ directory.
If you want a completely different location for the file, you need to add a filepath member to the options array, like this:
$target = array(
'target' => 'FILE',
'options' =>
array(
'filepath' => 'path/to/log/dir/',
'filename' => 'custom.log'
)
);
The filepath must end in a slash, the filename must not. You don't need to check to make sure the directory exists. It will be created automatically when the first log() call is made.
Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.