Craft makes it easy for you to add a log file for your plugin. Using the static method
PluginClassName::log(). Craft will create a new log file for you in the folder
craft/storage/runtime/logs and name it after your plugin using all lowercase letters
Sprout Active plugin as an example, in the most simple form, we would add the following line anywhere we wanted to output a message:
SproutActivePlugin::log('This is it.');
By default, the
log() behavior just outputs information, however, our
log() function can be refined a bit more if we need with three different log levels:
To log a warning or an error message, we just need to pass the appropriate
LogLevel as the second argument:
// Our default Log Level is Info SproutActivePlugin::log('Just sharing some information', LogLevel::Info); // We need to specifically add the second argument for Warnings and Errors SproutActivePlugin::log('Hey, watch out now!', LogLevel::Warning); SproutActivePlugin::log('Uh oh.', LogLevel::Error);
We will see the level of the log item appear in our log file:
2014/04/08 00:25:36 [info] [plugin] Just sharing some information 2014/04/08 00:25:36 [warning] [plugin] Hey, watch out now! 2014/04/08 00:25:36 [error] [plugin] Uh oh.
devMode is not enabled, you will only see log messages for warnings and errors in the logs. If
devMode is enabled, you will see all of the messages logged. Additionally, with
devMode enabled, Craft also adds a stack trace, which includes a bit more information about the files and methods that were triggered before your item got logged.
If you want a log item to appear regardless of whether
devMode is enabled, you can pass true as the third argument to the
SproutActivePlugin::log('Log this with or without devMode enabled.', LogLevel::Info, true);
If you'd like to see more examples, search for "Craft::log" in the Craft app folder and take a look at how Craft is handling its own log files. Craft's
Craft::log() method behaves just like the
Watching your log files #
There are several ways you can monitor and check your log files.
Via the filesystem - Open your file with your favorite text editor from the filesystem. Log files are stored in:
Via the Control Panel - Craft has a hidden Utility section in the control panel. You won't find a link to it, but it's just a segment or two away:
Via the console - A handy way to monitor your log files is using the
tail /path/to/craft/storage/runtime/logs/sproutactiveplugin.log. The
tailcommand will output your log messages to the console while you work.
Deprecating Features in your plugin #
If you need to deprecate a feature in one of your plugins that other folks might be using, Craft also has a way to log deprecation errors so that they will appear in the Deprecation Logs page in the Control Panel's hidden Utilities section, located at
You can do this using the Deprecation Service.
An actual example might look like the following. The key will make sure your message is only logged once in a request, and the message should clearly tell a user reading the message the steps they can take to fix the deprecation error.
craft()->deprecator->log('craft()->sproutActive->oldSchoolFunction()', 'craft()->sproutActive->oldSchoolFunction() has been deprecated. Use craft()->sproutActive->newFunction() instead.');