Presentation

It is absolutely necessary to be able to follow the execution of the code of an application. During development, or when we have to do some debugging, we want to know which functions are executed and in what order. For a production application, we want to trace all the errors, in order to be able to deal with them specifically.

Temma offers a logging mechanism based on the \Temma\Base\Log object.

Simple Log

The easiest way to write a log message is to call the static l() method, giving it the message to write to the log file as a parameter. The message can either be a character string (which will be displayed as is), or any PHP data (which will then be serialized with the print_r function).

Here are some examples:

use \Temma\Base\Log as TµLog;

TµLog::l("Message that will be written systematically");
TµLog::l(['zone' => 'internal', 'idx' => 3]);

• Line 1: We create an alias to facilitate the call to the log object.
• Line 3: The text message will necessarily appear in the log file.
• Line 4: The data provided as a parameter will also necessarily be written to the log file, after having been converted into a textual representation.

Advanced Log

To use it, just call the static log() method, providing it with 3 parameters (the first two are optional):

• A log class, that is to say a label which will allow the system to know the criticality threshold beyond which the message will appear.
• A level of criticality, in the form of a short character string, which is used to indicate whether it is a simple debugging message, or information reporting a critical error.
• The text of the log message. It can be a string (which will be displayed as is), or any PHP data (which will then be serialized with the print_r function).

Here is the list of criticality levels managed by \Temma\Base\Log:

• DEBUG: debugging message (lowest criticality)
• INFO: information message (default level of messages whose criticality is not specified)
• NOTE: notification; normal but meaningful message (default threshold)
• WARN: alert message; the application does not work normally but it can continue to work
• ERROR: error message; the application does not work normally and it must stop
• CRIT: critical error message; the application risks damaging its environment (highest criticality)

For a message to be written to the log file, its criticality level must be greater than or equal to the threshold provided for its log class. The log classes are defined in the temma.json configuration file (see Configuration).
A log message with an undefined criticality level is seen as an information message (INFO).
If the class of a message is not defined, it is assigned a default class, whose appearance threshold is NOTE.

Here are some examples:

use \Temma\Base\Log as TµLog;

TµLog::log("Log message using default thresholds.");
TµLog::log('NOTE', "Record linked to the default class.");
TµLog::log('myapp', 'DEBUG', "This is a debug message.");
TµLog::log('data', 'INFO', ['zone' => 'internal', 'idx' => 3]);

• Line 1: We create an alias to facilitate the call to the log object.
• Line 3: This message has a default criticality (INFO), and a default class (default, which threshold is NOTE). The criticality being less important than the threshold, the message will not appear.
• Line 4: This message has the criticality NOTE, and a default class (default, which threshold is NOTE). The criticality being equal to the threshold, the message will appear.
• Line 5: This message has the DEBUG criticality (least important), and is for the myapp class. If the threshold for this class is set to DEBUG, the message will appear.
• Line 6: This message has the criticality INFO, and the data class. If the threshold for this class is set to INFO or DEBUG, the message will appear. The message being an associative array, the log message will show it after conversion to text.

Log manager

In the temma.json configuration file, the logManager directive allows you to define an object (or more) that will take charge of the logs generated by the application (see the configuration documentation).
This can be useful if your logs need to be sent to a centralized server (Graylog, LogStash, Fluentd, rsyslog, syslog-ng, Nagios, ELK, Datadog…), and not only − or instead of − writing in a file.

A log manager is an object that implements the \Temma\Web\LogManager interface. It must contain a static log() method, which will be called on each new log message, receiving three parameters:

1. The text of the log message.
2. The priority of the message (DEBUG, NOTE, INFO,…). Can be null.
3. The "log class" of the message. Can be null.

Example:

/** Log manager that sends messages to a Syslog server. */
class SyslogManager implements \Temma\Web\LogManager {
    /**
     * Sends the application logs to the Syslog server of the local system.
     * @param  string   $text      Text of the message.
     * @param  ?string  $priority  Priority of the message.
     * @param  ?string  $class     Log class of the message.
     */
    static public function log(string $text, ?string $priority, ?string $class) {
        // syslog priority mapping table
        $prioMapping = [
            'DEBUG' => LOG_DEBUG,
            'INFO'  => LOG_INFO,
            'NOTE'  => LOG_NOTICE,
            'WARN'  => LOG_WARNING,
            'ERROR' => LOG_ERR,
            'CRIT'  => LOG_CRIT,
        ];
        // send to syslog
        $prio = $prioMapping[$priority] ?? LOG_NOTICE;
        syslog($prio, "$class $text");
    }
}

In this example, the Log Manager sends all log messages to the local system syslog server. The priority strings (DEBUG, INFO…) are converted into values that can be used by the PHP syslog() function (LOG_DEBUG, LOG_INFO…).

If the static log() method does not return anything (or returns null), the system will go to the next log handler (if a list of handlers had been configured) or finally to write to the temma.log file (unless the logFile directive was used to disable writing to the file).

If the method returns the false boolean value, the logging system will stop: the following handlers will not be executed, and the message will not be written to the temma.log file.

Finally, the method can return an associative array, containing one or more of the following keys:

• logPath: To change the writing path of the log file. It must be an absolute path.
• logToStdOut: Set to true, log messages will be written to standard output (and will therefore end up in the framework output stream).
• logToStdErr: Set to true, log messages will be written to the error output (and will end up in the HTTP server log file).