Logging

To help you learn more about what’s happening within your plugin, you can use the error_log() function. As you know, within WordPress, you can enable logging by adding the following lines in the wp-config.php file:

wp-config.php
/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * It is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments.
 */
 define('WP_DEBUG', true);
 define('WP_DEBUG_LOG', true );
 define('WP_DEBUG_DISPLAY', false );
 ini_set('display_errors', 0 );

This will create a debug.log file in the /wp-content/ folder. However, this is not the best way to log messages in your plugin.

WP Bones provides a more advanced logging system that allows you to log messages with different levels, such as debug, info, warning, error, and so on.

👆

Remember to enable the logging in the wp-config.php file as shown above. Otherwise, the WP Bones logger will not work.

Configuration

In the config/plugin.php file, you can configure the logging behavior of your plugin. You can set the logging type and the logging level.

config/plugin.php
<?php
if (!defined("ABSPATH")) {
  exit();
}
 
return [
  /*
  |--------------------------------------------------------------------------
  | Logging Configuration
  |--------------------------------------------------------------------------
  |
  | Here you may configure the log settings for your plugin.
  |
  */
 
  "logging" => [
    /**
     * Type of log.
     * Available Settings: "single", "daily", "errorlog".
     *
     * - "errorlog", the log will be saved in the default WordPress log file.
     * Usually, this is located in the wp-content/debug.log file.
     *
     * - "single", the log will be saved in a single file in the log_path directory.
     * Default: [plugin-path]/storage/logs/debug.log
     *
     * - "daily", the log will be saved in a daily file in the log_path directory.
     * Default: [plugin-path]/storage/logs/[Y-m-d].log
     * Example: [plugin-path]/storage/logs/2024-10-09.log
     */
    "type" => "errorlog",
 
    /**
     * The path where the log will be saved.
     * Default: [plugin-path]/storage/logs/
     */
    //"path" => '',
 
    /**
     * Daily format.
     * Default: 'Y-m-d'
     */
    "daily_format" => 'Y-m-d',
 
    /**
     * The timestamp format used in the log.
     * Default: 'd-M-Y H:i:s T'
     * Example: [09-Oct-2024 12:51:22 UTC] [debug]: This is a debug message
     */
    "timestamp_format" => 'd-M-Y H:i:s T',
  ],
  ...
];

Configuration options

  • type: The type of log. You can set it to errorlog, single, or daily.
  • path: The path where the log will be saved. By default, it is set to [plugin-path]/storage/logs/.
  • daily_format: The daily format for the log file. By default, it is set to Y-m-d.
  • timestamp_format: The timestamp format used in the log. By default, it is set to d-M-Y H:i:s T.

Log provider

The log provider is accessible through multiple methods, making it a versatile option that serves as an excellent alternative to the traditional error_log() function. This flexibility allows developers to choose the most suitable approach for their specific needs, enhancing the overall logging experience and improving error handling in their applications.

Accessing the log provider

You can access the log provider in several ways:

  • Global Plugin Instance Function: You can access the log provider through the global plugin instance function and use the log() method.
  • Log Class: You can access the log provider through the Log class and use the various logging methods.
  • Helper Function: You can access the log provider through the wpbones_logger() function and use the various logging methods.
1. by using the Plugin instance function
class MyClass {
 
  public function myMethod()
  {
    // By using the Plugin instance function
    WPKirk()->log()->debug( 'info', [ 'context' => 'any' ] );
  }
}
2. by using the Log class
use YourNamespace\WPBones\Foundation\Log\Log;
 
class MyClass {
 
  public function myMethod()
  {
    // By using the Log class
    Log::debug( 'info', [ 'context' => 'any' ] );
  }
}
3. by using the helper function
wpbones_logger()->debug('Hello, World');

Logging Levels

The log provider supports the eight logging levels defined in the RFC 5424 specification: emergency, alert, critical, error, warning, notice, info, and debug.

Example log output
[09-Oct-2024 17:25:22 UTC] [EMERGENCY]: Your message 
[09-Oct-2024 17:25:23 UTC] [ALERT]: Your message 
[09-Oct-2024 17:25:24 UTC] [CRITICAL]: Your message 
[09-Oct-2024 17:25:25 UTC] [ERROR]: Your message 
[09-Oct-2024 17:25:26 UTC] [WARNING]: Your message 
[09-Oct-2024 17:25:27 UTC] [NOTICE]: Your message 
[09-Oct-2024 17:25:28 UTC] [INFO]: Your message 
[09-Oct-2024 17:25:29 UTC] [DEBUG]: Your message 

Filtering log messages

The logging levels are color-coded for easy identification. In addition, they are useful for filtering and categorizing log messages based on their severity. For example, you may use a grep command to filter out specific log levels. Or find a specific log message in a large log file.

Filtering log messages
tail -f /path/to/debug.log | grep -E '\[ERROR\]|\[CRITICAL\]'

Messages and parameters

Usually, the log method accepts two parameters: the message and an array of context data. The context data can be any information you want to log, such as an array, object, or string.

wpbones_logger()->debug('Hello, World', [ 'context' => 'any' ]);
Example log output
[10-Oct-2024 06:03:34 UTC] [DEBUG]: Hello, World {
    "context": "any"
}

Save log files

Instead of using only the default WordPress log file, you can store the WP Bones logs into a file in the /storage/logs/ folder within your plugin folder. You can configure the log file type in the config/plugin.php file.

👆

If you decide to change the type setting to single or daily, you still will be able to see the log messages in the WordPress log file. The WP Bones logger will write the log messages to the file and in the error_log channel as well.

😎

Of course, in the WP Bones log file, you will find only the messages from the WP Bones logger. This means that you will not see the messages from the error_log() function. And you will not see any WordPress and PHP errors or notices.

Configuring the logging type

By default, the channel driver is set to errorlog. This means that you’ll find the WP Bones log in the default WordPress log file, usually /wp-content/debug.log. You may use the single or daily driver as well. In this case, you’ll find the log file in the /storage/logs/ folder within your plugin folder.

config/plugin.php
"logging" => [
  "type" => "single",
  "path" => null,
  "daily_format" => 'Y-m-d',
  "timestamp_format" => 'd-M-Y H:i:s T',
],

The single channel driver will create a single log file in /storage/logs/debug.log.

The daily channel driver will create a daily log file in /storage/logs/20180401.log.

Configuring the log path

Of course, you can change the log path in the config/plugin.php file. By default, the log path is set to {$plugin->basePath}/storage/logs/ within your plugin folder.

config/plugin.php
"logging" => [
  "type" => "single",
  "path" => "../logs/",
  "daily_format" => 'Y-m-d',
  "timestamp_format" => 'd-M-Y H:i:s T',
],
👆

To use the default path (in general that is true for the all configurations in the config/plugin.php file), comment out the path setting.

config/plugin.php
"logging" => [
  "type" => "single",
  //"path" => "",
  "daily_format" => 'Y-m-d',
  "timestamp_format" => 'd-M-Y H:i:s T',
],

Configuring the daily format

You can change the daily format in the config/plugin.php file. By default, the daily format is set to Y-m-d.

config/plugin.php
"logging" => [
  "type" => "daily",
  "daily_format" => 'Y-m-d',
  "timestamp_format" => 'd-M-Y H:i:s T',
],

Tips for the daily format

If you want to create a log file for each hour, you can set the daily format to Y-m-d-H. This will create a log file for each hour.

Per hour
config/plugin.php
"logging" => [
  "type" => "daily",
  "daily_format" => 'Y-m-d-H',
  "timestamp_format" => 'd-M-Y H:i:s T',
],
With prefix name

You may also add a prefix by using the | pipe character. For example, if you want to create a log file for each hour with a prefix, you can set the daily format to my-log-|Y-m-d.

config/plugin.php
"logging" => [
  "type" => "daily",
  "daily_format" => 'my-log-|Y-m-d',
  "timestamp_format" => 'd-M-Y H:i:s T',
],

You will get the log file with the name my-log-2024-10-09.log.