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:

/**
 * 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.

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.

<?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.

class MyClass {
 
  public function myMethod()
  {
    // By using the Plugin instance function
    WPKirk()->log()->debug( 'info', [ 'context' => 'any' ] );
  }
}

use YourNamespace\WPBones\Foundation\Log\Log;
 
class MyClass {
 
  public function myMethod()
  {
    // By using the Log class
    Log::debug( 'info', [ 'context' => 'any' ] );
  }
}

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.

[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.

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' ]);

[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.

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.

"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.

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

"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.

"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

"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.

"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.