{eac}Doojigger has a built-in Debugging Doololly extension that allows several options, including what types of log entries are actually logged - Information, Notices, Warnings, Errors & Exceptions, Debugging.

Also included are several logging methods that fall into these categories.

PSR-3 Logging Method

First, the built in logger uses the PSR-3: Logger Interface and includes an easy to use log method:

public function log($level = '', string|\Stringable $message = '', array $context = [])

• $level - a PSR-3 LogLevel string or a PHP ErrorLevel integer.
• $message - the message to be logged
• $context - an optional key=>value array used to interpolate $message

$this->log('error', 'This is a fatal error message');
$this->log(E_USER_ERROR, 'This is a fatal error message');

$message = 'Account {account} has been deleted';
$context = ['account' => $account_num];
$this->log('notice', $message, $context);

$context MAY contain @source (max 20 characters) to indicate the source identifier (the calling class or function) of the message (eacDoojigger uses the short class name by default).

$context['@source'] = basename(str_replace('\\', '/', get_class($this)));

The log method may also be used to retrieve an instance of the Logger object and to call PSR-3 logger methods:

$this->log()->critical('This is a critical error message');
$logger = $this->log();
$logger->warning('This is a warning message');

Preferred Logging Methods

Additionally, there are preferred logging methods (with a different signature) that set $level and allow for logging of any type of variable (strings, arrays, objects, etc.):

Information

public function logInfo($variable, $message=null, array $context = []): void

Notices

public function logNotice($variable, $message=null, array $context = []): void

Warnings

public function logWarning($variable, $message=null, array $context = []): void

Errors & Exceptions

public function logError($variable, $message=null, array $context = []): void

Debugging

public function logDebug($variable, $message=null, array $context = []): void

And to always log, regardless of selected levels

public function logAlways($variable, $message=null, array $context = []): void

Lastly, the logWrite method allows you to set the logging level using PSR-3 LogLevel or PHP ErrorLevel:

public function logWrite($level, $variable, $message=null, array $context = []): void

Typically, eacDoojigger uses these methods to log a data structure and to indicate where the log statement originated:

$this->logDebug($data, __METHOD__);
$this->logDebug($data, current_action());

Accessing Log Data

eacDoojigger's logging object doesn't actually write any log files, that is handled by the debugging extension which 'subscribes' to the logging data.

You can write your own method or function to access this data...

1. Subscribe to the logger (in a plugins_loaded action):

$this->log()->subscribe( [ $this, 'my_log_data' ] );

2. Define your method to receive the data:

public function my_log_data( $data ) {...}

$data is an array:

• level - LogLevel::LOG_ERROR/LOG_WARNING/LOG_NOTICE/LOG_DEBUG/LOG_ALWAYS
• message - the message to be logged
• context - the context array
• error_code - PHP ErrorLevel or PSR-3 LogLevel
• print_code - textual error code

The context array MAY contain:

• a @variable element holding any type of variable passed with this log entry.
• a wp_error element if the log() call passed a WP_ERROR object.
• a php_error element if the log() call passed a PHP error.
• a exception element if the log() call passed a throwable/exception object.

Here is a very simple example that displays the print_code and message:

eacDoojigger()->Log()->subscribe(function($data)
    {
        $message = sprintf('%s: %s',$data['print_code'],$data['message']);
        echo "<div class='notice'>".$message."</div>";
    }
);

Notice

• As with all eacDoojigger methods, when working within a Doojigger plugin, or a Doololly extension class, use $this-> or $this->plugin-> to call the method. When working from outside of the eacDoojigger environment (i.e. in functions.php) use eacDoojigger()->.

\eacDoojigger()->logDebug($structure, current_action());

• The debugging extension creates log files in either the same place as the WP debug.log (if WP_DEBUG_LOG is set to a pathname), the WP uploads folder, or the WP content folder.

• Debugging and logging should only be used on staging sites and/or only when necessary.

• Enabling the debugging extension and using the logger will add some overhead to your site.

• Enabling the debugging extension and using the logger may add some security risks to your site.

  • If possible, set WP_DEBUG_LOG to a path outside of your web space.

Example Debugging Output

--- Wed Aug 28 2024 EDT  via https  [19:28:56.7008] - IP:n.n.n.n HTTP/1.1 POST https://earthasylum.com/wp-login.php
--- eacDoojigger         -----      [19:28:56.7364] - EarthAsylumConsulting\Plugin\eacDoojigger: version 2.6.1 2024-07-14 09:46:50
--- eacDoojigger         critical   [19:28:56.7714] - This is a critical message
--- eacDoojigger         emergency  [19:28:56.7714] - This is an emergency message
--- eacDoojigger         notice     [19:28:56.7714] - This is a notice message
--- eacDoojigger         debug      [19:28:56.7714] - This is a debug message with an empty array: array (
)
--- eacDoojigger         error      [19:28:56.7717] - wp_error object: array (
  'WP_Error' => 
  array (
    'code' => 'error_code',
    'message' => 'WP_ERROR passed as $variable',
    'data' => NULL,
  ),
)
--- phpErrorHandler      warning    [19:28:56.7718] - ltrim(): Passing null to parameter #1 ($string) of type string is deprecated: array (
    [type] => Deprecated
    [message] => ltrim(): Passing null to parameter #1 ($string) of type string is deprecated
    [file] => wp-includes/formatting.php
    [line] => 4482
)
--- exit https                      [19:28:57.0860] - Duration: 0.3852 Seconds, Peak Memory Used: 16M of 192M