README

Robust, composite PSR-3 compliant logger with filtering and formatting.

Version History

Branch	Service Manager	Log style implementation	PHP Version
5.0	Service Manager 4	PSR-Log
4.1	Service Manager 4	Laminas Log style
4.0	Service Manager 3	Laminas Log style
3.0	Service Manager 3	Laminas Log

Documentation

Documentation is available at: https://docs.dotkernel.org/dot-log/.

Badges

Adding The Config Provider

• Enter config/config.php
• If there is no entry for the config provider below, add it: \Dot\Log\ConfigProvider::class
• Make sure it is added before with the Application-Specific components, e.g.: \Frontend\App\ConfigProvider.php, \Admin\App\ConfigProvider::class, MyProject\ConfigProvider::class , etc.
• Open the Dot\Log\ConfigProvider
• In the dependencies section you will see an abstract factory (LoggerAbstractServiceFactory::class)
• This class responds to "selectors" instead of class names Instead of requesting the Dot\Log\Logger::class from the container, dot-log.my_logger should be requested

Configuring the writer(s)

Loggers must have at least one writer.

A writer is an object that inherits from Dot\Log\Writer\AbstractWriter. A writer's responsibility is to record log data to a storage backend.

Writing to a file (stream)

It is possible to separate logs into multiple files using writers and filters. For example, warnings.log, errors.log, all_messages.log.

The following is the simplest example to write all log messages to /log/dk.log

return [
    'dot_log' => [
        'loggers' => [
            'my_logger' => [
                'writers' => [
                     'FileWriter' => [
                        'name' => 'FileWriter',
                        'level'   => \Dot\Log\Logger::ALERT, // this is equal to 1
                        'options' => [
                            'stream' => __DIR__ . '/../../log/dk.log',
                        ],
                    ],
                ],
            ]
        ],
    ],
];

• The FileWriter key is optional, otherwise the writers array would be enumerative instead of associative.
• The writer name key is a developer-provided name for that writer, the writer name key is mandatory.

The writer level key is not affecting the errors that are written; it is a way to organize writers.

The writer level key is optional.

To write into a file, the key stream must be present in the writer options array. This is required only if writing into streams/files.

Grouping log files by date

By default, logs will be written to the same file: log/dk.log. Optionally, you can use date format specifiers wrapped between curly braces in your FileWriter's stream option, automatically grouping your logs by day, week, month, year, etc. Examples:

• log/dk-{Y}-{m}-{d}.log will write every day to a different file (eg: log/dk-2021-01-01.log)
• log/dk-{Y}-{W}.log will write every week to a different file (eg: log/dk-2021-10.log)

The full list of format specifiers is available in the official documentation.

Filtering log messages

As per PSR-3 document.

The log levels are: emergency (0), alert (1), critical (2), error (3), warn (4), notice (5), info (6), debug (7) (in order of level/importance)

The following example has three file writers using filters:

• First Example: FileWriter - All messages are logged in /log/dk.log
• Second Example: OnlyWarningsWriter - Only warnings are logged in /log/warnings.log
• Third Example: WarningOrHigherWriter - All important messages (warnings or more critical) are logged in /log/important_messages.log

<?php

return [
    'dot_log' => [
        'loggers' => [
            'my_logger' => [
                'writers' => [
                    'FileWriter' => [
                        'name'    => 'FileWriter',
                        'level'   => \Dot\Log\Logger::ALERT,
                        'options' => [
                            'stream' => __DIR__ . '/../../log/dk.log',
                            'filters' => [
                                'allMessages' => [
                                    'name' => 'level',
                                    'options' => [
                                        'operator' => '>=', 
                                        'level'    => \Dot\Log\Logger::EMERG,
                                    ]
                                ],
                            ],
                        ],
                    ],
                    // Only warnings
                    'OnlyWarningsWriter' => [
                        'name'  => 'stream',
                        'level' => \Dot\Log\Logger::ALERT,
                        'options' => [
                            'stream' => __DIR__ . '/../../log/warnings_only.log',
                            'filters' => [
                                'warningOnly' => [
                                    'name' => 'level',
                                    'options' => [
                                        'operator' => '==',
                                        'level'    => \Dot\Log\Logger::WARN,
                                    ],
                                ],
                            ],
                        ],
                    ],
                    // Warnings and more important messages
                    'WarningOrHigherWriter' => [
                        'name' => 'stream',
                        'level' => \Dot\Log\Logger::ALERT,
                        'options' => [
                            'stream' => __DIR__ . '/../../log/important_messages.log',
                            'filters' => [
                                'importantMessages' => [
                                    'name'    => 'level',
                                    'options' => [
                                        // note, the smaller the level, the more important the message
                                        // 0 - emergency, 1 - alert, 2- error, 3 - warn. .etc
                                        'operator' => '<=',
                                        'level'    => \Dot\Log\Logger::WARN,
                                    ],
                                ],
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
];

As in the writer configuration, the developer can optionally use keys for associating the filters with a name.

IMPORTANT NOTE: the operator for more important messages is <=, this is because the number representation is smaller for a more important message type.

The filter added on the first writer is equal to not setting a filter, but it has been added to illustrate how to explicitly allow all messages.

It was added opposite to the others just to demonstrate the other operator is also an option.

Formatting Messages

When using dot-log, the logged value is not limited to a string. Arrays can be logged as well.

For better readability, these arrays can be serialized.

Dot Log provides String formatting and JSON formatting.

The formatter accepts the following parameters:

• name: the formatter class (it must implement Dot\Log\Formatter\FormatterInterface)
• options: options to pass to the formatter constructor if required

The following formats the message as JSON data:

'formatter' => [
    'name' => \Dot\Log\Formatter\Json::class,
],

Example with formatter

• The log is used through dot-log
• The logger name is my_logger
• Writes to file: log/dk.log
• Explicitly allows all the messages to be written
• Formats the messages as JSON

<?php


return [
    'dot_log' => [
        'loggers' => [
            'my_logger' => [
                'writers' => [
                    'FileWriter' => [
                        'name'    => 'FileWriter',
                        'level'   => \Dot\Log\Logger::ALERT,
                        'options' => [
                            'stream' => __DIR__ . '/../../log/dk.log',
                            // explicitly log all messages
                            'filters' => [
                                'allMessages' => [
                                    'name'    => 'level',
                                    'options' => [
                                        'operator' => '>=',
                                        'level'    => \Dot\Log\Logger::EMERG,
                                    ],
                                ],
                            ],
                            'formatter' => [
                                'name' => \Dot\Log\Formatter\Json::class,
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
];

Usage

Basic usage of the logger is illustrated below.

The messages are written to see which logs are written and which are not written.

/** @var \Dot\Log\Logger $logger */
$logger = $container->get('dot-log.my_logger');

$logger->emergency('0 EMERG');
$logger->alert('1 ALERT');
$logger->critical('2 CRITICAL');
$logger->error('3 ERR');
$logger->warning('4 WARN');
$logger->notice('5 NOTICE');
$logger->info('6 INF');
$logger->debug('7 debug');
$logger->log(Logger::NOTICE, 'NOTICE from log()');