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:

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

• Line 1: The text message will necessarily appear in the log file.
• Line 2: The data provided as a parameter will also necessarily be written to the log file, after having been converted into a textual representation.

To facilitate calls to the log object, an alias can be used:

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

TµLog::l("Message that will be written systematically");

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 INFO criticality, 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 system will show it after conversion to text.

Log control

It is possible to modify the behavior of the log, by calling static methods of the \Temma\Base\Log object:

• disable() to disable logging.
• enable() to reactivate the log.
• logToStdOut() to enable log writing to standard output. It can take an optional boolean parameter (true to enable, false to disable).
• logToStdErr() to enable writing the log to the error output. It can take an optional boolean parameter (true to enable, false to disable).
• setLogFile($path) to redefine the path to the log file.

Usually, there is no need to call these methods, the log system being initialized by the framework.