From 3cf57c61edbfd5f73f7dead6a2c2323b90c64081 Mon Sep 17 00:00:00 2001 From: Sergiu Date: Wed, 28 Aug 2024 10:25:46 +0300 Subject: [PATCH] updated docs --- docs/book/v3/configuring-writer.md | 2 +- docs/book/v3/example-with-formatter.md | 6 +- docs/book/v3/filtering-log-messages.md | 12 +-- docs/book/v3/usage.md | 2 +- docs/book/v4/adding-config-provider.md | 10 +++ docs/book/v4/configuring-writer.md | 46 ++++++++++ docs/book/v4/example-with-formatter.md | 41 +++++++++ docs/book/v4/filtering-log-messages.md | 97 ++++++++++++++++++++++ docs/book/v4/formatting-messages.md | 14 ++++ docs/book/v4/grouping-log-files-by-date.md | 12 +++ docs/book/v4/overview.md | 5 ++ docs/book/v4/usage.md | 26 ++++++ mkdocs.yml | 14 +++- 13 files changed, 274 insertions(+), 13 deletions(-) create mode 100644 docs/book/v4/adding-config-provider.md create mode 100644 docs/book/v4/configuring-writer.md create mode 100644 docs/book/v4/example-with-formatter.md create mode 100644 docs/book/v4/filtering-log-messages.md create mode 100644 docs/book/v4/formatting-messages.md create mode 100644 docs/book/v4/grouping-log-files-by-date.md create mode 100644 docs/book/v4/overview.md create mode 100644 docs/book/v4/usage.md diff --git a/docs/book/v3/configuring-writer.md b/docs/book/v3/configuring-writer.md index 3531f0e..a9ed716 100644 --- a/docs/book/v3/configuring-writer.md +++ b/docs/book/v3/configuring-writer.md @@ -18,7 +18,7 @@ return [ 'writers' => [ 'FileWriter' => [ 'name' => 'FileWriter', - 'priority' => \Dot\Log\Manager\Logger::ALERT, // this is equal to 1 + 'priority' => \Laminas\Log\Logger::ALERT, // this is equal to 1 'options' => [ 'stream' => __DIR__ . '/../../log/dk.log', ], diff --git a/docs/book/v3/example-with-formatter.md b/docs/book/v3/example-with-formatter.md index de6460b..ed8b278 100644 --- a/docs/book/v3/example-with-formatter.md +++ b/docs/book/v3/example-with-formatter.md @@ -15,7 +15,7 @@ return [ 'writers' => [ 'FileWriter' => [ 'name' => 'FileWriter', - 'priority' => \Dot\Log\Manager\Logger::ALERT, + 'priority' => \Laminas\Log\Logger::ALERT, 'options' => [ 'stream' => __DIR__ . '/../../log/dk.log', // explicitly log all messages @@ -24,12 +24,12 @@ return [ 'name' => 'priority', 'options' => [ 'operator' => '>=', - 'priority' => \Dot\Log\Manager\Logger::EMERG, + 'priority' => \Laminas\Log\Logger::EMERG, ], ], ], 'formatter' => [ - 'name' => \Dot\Log\Manager\Formatter\Json::class, + 'name' => \Laminas\Log\Formatter\Json::class, ], ], ], diff --git a/docs/book/v3/filtering-log-messages.md b/docs/book/v3/filtering-log-messages.md index da1aac7..32c185f 100644 --- a/docs/book/v3/filtering-log-messages.md +++ b/docs/book/v3/filtering-log-messages.md @@ -31,7 +31,7 @@ return [ 'writers' => [ 'FileWriter' => [ 'name' => 'FileWriter', - 'priority' => \Dot\Log\Manager\Logger::ALERT, + 'priority' => \Laminas\Log\Logger::ALERT, 'options' => [ 'stream' => __DIR__ . '/../../log/dk.log', 'filters' => [ @@ -39,7 +39,7 @@ return [ 'name' => 'priority', 'options' => [ 'operator' => '>=', - 'priority' => \Dot\Log\Manager\Logger::EMERG, + 'priority' => \Laminas\Log\Logger::EMERG, ] ], ], @@ -48,7 +48,7 @@ return [ // Only warnings 'OnlyWarningsWriter' => [ 'name' => 'stream', - 'priority' => \Dot\Log\Manager\Logger::ALERT, + 'priority' => \Laminas\Log\Logger::ALERT, 'options' => [ 'stream' => __DIR__ . '/../../log/warnings_only.log', 'filters' => [ @@ -56,7 +56,7 @@ return [ 'name' => 'priority', 'options' => [ 'operator' => '==', - 'priority' => \Dot\Log\Manager\Logger::WARN, + 'priority' => \Laminas\Log\Logger::WARN, ], ], ], @@ -65,7 +65,7 @@ return [ // Warnings and more important messages 'WarningOrHigherWriter' => [ 'name' => 'stream', - 'priority' => \Dot\Log\Manager\Logger::ALERT, + 'priority' => \Laminas\Log\Logger::ALERT, 'options' => [ 'stream' => __DIR__ . '/../../log/important_messages.log', 'filters' => [ @@ -75,7 +75,7 @@ return [ // note, the smaller the priority, the more important is the message // 0 - emergency, 1 - alert, 2- error, 3 - warn etc. 'operator' => '<=', - 'priority' => \Dot\Log\Manager\Logger::WARN, + 'priority' => \Laminas\Log\Logger::WARN, ], ], ], diff --git a/docs/book/v3/usage.md b/docs/book/v3/usage.md index e479b9c..fea781e 100644 --- a/docs/book/v3/usage.md +++ b/docs/book/v3/usage.md @@ -5,7 +5,7 @@ Basic usage of the logger is illustrated below. The messages are written to see which logs are written and which are not written. ```php -use Dot\Log\Manager\Logger; +use Laminas\Log\Logger; ``` ... diff --git a/docs/book/v4/adding-config-provider.md b/docs/book/v4/adding-config-provider.md new file mode 100644 index 0000000..e591844 --- /dev/null +++ b/docs/book/v4/adding-config-provider.md @@ -0,0 +1,10 @@ +# Adding The Config Provider + +* In `config/config.php` add an entry for the config provider `\Dot\Log\ConfigProvider::class` + * Make sure it is added before with the Application-Specific components, eg.: + * `\Frontend\App\ConfigProvider.php` + * `\Admin\App\ConfigProvider::class` + * `\MyProject\ConfigProvider::class` etc. +* Add the logger configuration in an autoload config file, e.g. you can create `config/autoload/logger.global.php`. Follow the `Configuring the writer(s)` chapter for a simple working example. + +Note: `Dot\Log\ConfigProvider` has an abstract factory `LoggerAbstractServiceFactory::class` which corresponds to the alias, not the class name. Instead of requesting `Laminas\Log\Logger::class` from the container, use `dot-log.my_logger` (or just `my_logger` if using laminas-log). diff --git a/docs/book/v4/configuring-writer.md b/docs/book/v4/configuring-writer.md new file mode 100644 index 0000000..3531f0e --- /dev/null +++ b/docs/book/v4/configuring-writer.md @@ -0,0 +1,46 @@ +# Configuring the writer(s) + +Loggers must have at least one writer. + +A writer is an object that inherits from `Laminas\Log\Writer\AbstractWriter`. A writer's responsibility is to record log data to a storage backend. (from laminas-log's writer documentation) + +## Writing to a file (stream) + +You can 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` + +```php +return [ + 'dot_log' => [ + 'loggers' => [ + 'my_logger' => [ + 'writers' => [ + 'FileWriter' => [ + 'name' => 'FileWriter', + 'priority' => \Dot\Log\Manager\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 `name` key is a developer-provided name for that writer, the writer name key is **mandatory**. + +The `priority` key does not affect the errors that are written. It is a way to organize writers, for example: + +* 1 - FILE +* 2 - SQL +* 3 - E-mail + +The most important things to write in the file, the sql or e-mail are usually fails because the servers can be external and offline, but the file is on the same server. + +The `priority` key is optional. + +The key `stream` is required only if writing into streams/files. diff --git a/docs/book/v4/example-with-formatter.md b/docs/book/v4/example-with-formatter.md new file mode 100644 index 0000000..de6460b --- /dev/null +++ b/docs/book/v4/example-with-formatter.md @@ -0,0 +1,41 @@ +# Example with formatter + +* The log is used through `dot-log` +* The logger name is `my_logger` +* It writes to file: `log/dk.log` +* It is configured to explicitly write all messages +* The messages are formatted as JSON + +```php + [ + 'loggers' => [ + 'my_logger' => [ + 'writers' => [ + 'FileWriter' => [ + 'name' => 'FileWriter', + 'priority' => \Dot\Log\Manager\Logger::ALERT, + 'options' => [ + 'stream' => __DIR__ . '/../../log/dk.log', + // explicitly log all messages + 'filters' => [ + 'allMessages' => [ + 'name' => 'priority', + 'options' => [ + 'operator' => '>=', + 'priority' => \Dot\Log\Manager\Logger::EMERG, + ], + ], + ], + 'formatter' => [ + 'name' => \Dot\Log\Manager\Formatter\Json::class, + ], + ], + ], + ], + ], + ], + ], +]; +``` diff --git a/docs/book/v4/filtering-log-messages.md b/docs/book/v4/filtering-log-messages.md new file mode 100644 index 0000000..da1aac7 --- /dev/null +++ b/docs/book/v4/filtering-log-messages.md @@ -0,0 +1,97 @@ +# Filtering log messages + +The following conforms to the `PSR-3: Logger Interface` document. + +The log levels are in order of priority/importance: + +* emergency (0) +* alert (1) +* critical (2) +* error (3) +* warning (4) +* notice (5) +* info (6) +* debug (7) + +Although the plain Logger in `laminas-log` is not fully compatible with PSR-3, it provides a way to log all of these message types. + +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 critical) are logged in `/log/important_messages.log` + +```php + [ + 'loggers' => [ + 'my_logger' => [ + 'writers' => [ + 'FileWriter' => [ + 'name' => 'FileWriter', + 'priority' => \Dot\Log\Manager\Logger::ALERT, + 'options' => [ + 'stream' => __DIR__ . '/../../log/dk.log', + 'filters' => [ + 'allMessages' => [ + 'name' => 'priority', + 'options' => [ + 'operator' => '>=', + 'priority' => \Dot\Log\Manager\Logger::EMERG, + ] + ], + ], + ], + ], + // Only warnings + 'OnlyWarningsWriter' => [ + 'name' => 'stream', + 'priority' => \Dot\Log\Manager\Logger::ALERT, + 'options' => [ + 'stream' => __DIR__ . '/../../log/warnings_only.log', + 'filters' => [ + 'warningOnly' => [ + 'name' => 'priority', + 'options' => [ + 'operator' => '==', + 'priority' => \Dot\Log\Manager\Logger::WARN, + ], + ], + ], + ], + ], + // Warnings and more important messages + 'WarningOrHigherWriter' => [ + 'name' => 'stream', + 'priority' => \Dot\Log\Manager\Logger::ALERT, + 'options' => [ + 'stream' => __DIR__ . '/../../log/important_messages.log', + 'filters' => [ + 'importantMessages' => [ + 'name' => 'priority', + 'options' => [ + // note, the smaller the priority, the more important is the message + // 0 - emergency, 1 - alert, 2- error, 3 - warn etc. + 'operator' => '<=', + 'priority' => \Dot\Log\Manager\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 equivalent to not setting a filter, but it was added to illustrate the usage of the operator to explicitly allow all messages. + +More examples on filters: https://docs.laminas.dev/laminas-log/filters/ diff --git a/docs/book/v4/formatting-messages.md b/docs/book/v4/formatting-messages.md new file mode 100644 index 0000000..c0b028a --- /dev/null +++ b/docs/book/v4/formatting-messages.md @@ -0,0 +1,14 @@ +# Formatting Messages + +When using `dot-log` or `laminas-log`, the logged value is not limited to a string. Arrays can be logged as well. For better readability, these arrays can be serialized. Laminas Log provides String, XML, JSON and FirePHP formatting. + +The formatter accepts following parameters: + +* name - the formatter class (it must implement `Laminas\Log\Formatter\FormatterInterface`) +* options - passed to the formatter constructor if required + +The following snippet formats the message as JSON data: + + 'formatter' => [ + 'name' => \Laminas\Log\Formatter\Json::class, + ], diff --git a/docs/book/v4/grouping-log-files-by-date.md b/docs/book/v4/grouping-log-files-by-date.md new file mode 100644 index 0000000..7437b4e --- /dev/null +++ b/docs/book/v4/grouping-log-files-by-date.md @@ -0,0 +1,12 @@ +# 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 to automatically group your logs by day, week, month, year etc. + +Examples: + +* `log/dk-{Y}-{m}-{d}.log` will create a new log file each day (eg: log/dk-2021-01-01.log) +* `log/dk-{Y}-{W}.log` will create a new log file each week (eg: log/dk-2021-10.log) + +The full list of format specifiers is available [here](https://www.php.net/manual/en/datetime.format.php). diff --git a/docs/book/v4/overview.md b/docs/book/v4/overview.md new file mode 100644 index 0000000..975a06d --- /dev/null +++ b/docs/book/v4/overview.md @@ -0,0 +1,5 @@ +# Overview + +> dot-log is a wrapper on top of [laminas-log](https://github.com/laminas/laminas-log) +> +> ![OSS Lifecycle](https://img.shields.io/osslifecycle/laminas/laminas-log) diff --git a/docs/book/v4/usage.md b/docs/book/v4/usage.md new file mode 100644 index 0000000..e479b9c --- /dev/null +++ b/docs/book/v4/usage.md @@ -0,0 +1,26 @@ +# Usage + +Basic usage of the logger is illustrated below. + +The messages are written to see which logs are written and which are not written. + +```php +use Dot\Log\Manager\Logger; +``` + +... + +```php +$logger = $container->get('dot-log.my_logger'); + +/** @var Logger $logger */ +$logger->emerg('0 EMERG'); +$logger->alert('1 ALERT'); +$logger->crit('2 CRITICAL'); +$logger->err('3 ERR'); +$logger->warn('4 WARN'); +$logger->notice('5 NOTICE'); +$logger->info('6 INF'); +$logger->debug('7 debug'); +$logger->log(Logger::NOTICE, 'NOTICE from log()'); +``` diff --git a/mkdocs.yml b/mkdocs.yml index a395ddc..49551bc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,11 +2,21 @@ docs_dir: docs/book site_dir: docs/html extra: project: Packages - current_version: v3 + current_version: v4 versions: + - v4 - v3 nav: - Home: index.md + - v4: + - "Overview": v4/overview.md + - "Adding The Config Provider": v4/adding-config-provider.md + - "Configuring the writer(s)": v4/configuring-writer.md + - "Grouping log files by date": v4/grouping-log-files-by-date.md + - "Filtering log messages": v4/filtering-log-messages.md + - "Formatting Messages": v4/formatting-messages.md + - "Example with formatter": v4/example-with-formatter.md + - "Usage": v4/usage.md - v3: - "Overview": v3/overview.md - "Adding The Config Provider": v3/adding-config-provider.md @@ -17,7 +27,7 @@ nav: - "Example with formatter": v3/example-with-formatter.md - "Usage": v3/usage.md site_name: dot-log -site_description: "DotKernel log component extending and customizing laminas-log" +site_description: "DotKernel log component" repo_url: "https://github.com/dotkernel/dot-log" plugins: - search