SugarLogger

Overview

The SugarLogger is used for log reporting by the application. The following article outlines the LoggerTemplate interface as well as the LoggerManager object and explains how to programmatically use the SugarLogger.

LoggerTemplate

The LoggerManager manages those objects that implement the LoggerTemplate interface found in ./include/SugarLogger/LoggerTemplate.php. 

Methods

log($method, $message)

The LoggerTemplate has a single method that should be implemented, which is the log() method.

Arguments

Implementations

Sugar comes with two stock LoggerTemplate implementations that can be utilized for different scenarios depending on your needs. You can extend from these implementations or create your own class that implements the template as outlined in Creating Custom Loggers section.

SugarLogger

The SugarLogger class, found in ./include/SugarLogger/SugarLogger.php, is the default system logging class utilized throughout the majority of Sugar. 

SugarPsrLogger

The SugarPsrLogger was added in Sugar 7.9 to accommodate the PSR-3 compliant logging implementation. This logger works just like the SugarLogger object, however it uses the Monolog implementation of Logger.

To configure the SugarPsrLogger as the default system logger, you can add the following to your configuration:

$sugar_config['logger']['default'] = 'SugarPsrLogger';

Log Level Mappings

PSR-3 defines the set of log levels that should be implemented for all PHP Applications, however, these are different from the log levels defined by the SugarLogger. Below is the list of SugarLogger log levels and their SugarPsrLogger compatible mapping. All calls to the SugarLogger log levels are mapped according to the table below. For example, when using the SugarPsrLogger class, all calls to the  fatal() method will map to the Alert log level.

LoggerManager

The LoggerManager Object acts as a singleton factory that sets up the configured logging object for use throughout the system. This is the object stored in $GLOBALS['log'] in the majority of use cases in the system.

Methods

getLogger()

This method is used to get the currently configured Logger class.

setLevel($level)

You may find that you want to define the log level while testing your code without modifying the configuration. This can be done by using the setLevel() method.

Arguments

Example

\LoggerManager::getLogger()->setLevel('debug');

Note: The use of setLevel should be removed from your code for production and it is important to note that it is restricted by package scanner as defined by the Module Loader Restrictions.

assert($message, $condition)

In your custom code you may want to submit a debug level log, should a condition not meet your expectations. You could do this with an if statement, otherwise you could just use the assert() method as it allows you to pass the debug message, and the condition to check, and if that condition is FALSE a debug level message is logged.

Arguments

Example

$x = 1;
\LoggerManager::getLogger()->assert('X was not equal to 0!', $x==0)

wouldLog($level)

If in your customization you find that extra debugging is needed for particular area of code, and that extra work might have performance impacts on standard log levels, you can use the wouldLog() method to check the current log level before doing the extra work.

Arguments

Example

if (\LoggerManager::getLogger()->wouldLog('debug')) {
   //Do extra debugging
}

setLogger($level, $logger)

This method allows you to setup a second logger for a specific log level, rather than just using the same logger for all levels. Passing default as the level, will set the default Logger used by all levels in the system.

Arguments

Example

//Set the debug level to a custom Logger
\LoggerManager::getLogger()->setLogger('debug', 'CustomLogger');

//Set all other levels to SugarPsrLogger
\LoggerManager::getLogger()->setLogger('default', 'SugarPsrLogger');

getAvailableLoggers()

Returns a list of the names of Loggers found/installed in the system.

Arguments

None

Example

$loggers = \LoggerManager::getLogger()->getAvailableLoggers();

getLoggerLevels()

Returns a list of the names of Loggers found/installed in the system.

Arguments

None

Example

$levels = \LoggerManager::getLogger()->getLoggerLevels();

Adding a Custom SugarLogger

Custom loggers are defined in ./custom/include/SugarLogger/, and can be used to write log entries to a centralized application management tool, to a developer tool such as FirePHP or even to a secondary log file inside the Sugar application.

The following is an example of how to create a FirePHP logger.

./custom/include/SugarLogger/FirePHPLogger.php.

<?php

// change the path below to the path to your FirePHP install
require_once('/path/to/fb.php');

class FirePHPLogger implements LoggerTemplate
{
    /** Constructor */
    public function __construct()
    {
        if (
            isset($GLOBALS['sugar_config']['logger']['default'])
            && $GLOBALS['sugar_config']['logger']['default'] == 'FirePHP'
        )
        {
            LoggerManager::setLogger('default','FirePHPLogger');
        }
    }

    /** see LoggerTemplate::log() */
    public function log($level, $message)
    {
        // change to a string if there is just one entry
        if ( is_array($message) && count($message) == 1 ) {
            $message = array_shift($message);
        }

        switch ($level) {
            case 'debug':
                FB::log($message);
                break;
            case 'info':
                FB::info($message);
                break;
            case 'deprecated':
            case 'warn':
                FB::warn($message);
                break;
            case 'error':
            case 'fatal':
            case 'security':
                FB::error($message);
                break;
        }
    }
}

You will then specify your default logger as 'FirePHP' in your ./config_override.php file.

$sugar_config['logger']['default'] = 'FirePHP';