From 8c1127c5a8bf611d836794a62b02428962bac856 Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 17 May 2024 13:39:45 +0300 Subject: [PATCH 1/2] updated docs --- docs/book/v3/adding-config-provider.md | 16 +++++----- docs/book/v3/configuring-writer.md | 20 ++++++------ docs/book/v3/example-with-formatter.md | 37 +++------------------- docs/book/v3/filtering-log-messages.md | 25 +++++++++------ docs/book/v3/formatting-messages.md | 18 ++++------- docs/book/v3/grouping-log-files-by-date.md | 8 +++-- 6 files changed, 51 insertions(+), 73 deletions(-) diff --git a/docs/book/v3/adding-config-provider.md b/docs/book/v3/adding-config-provider.md index f4e44bd..eeb75d2 100644 --- a/docs/book/v3/adding-config-provider.md +++ b/docs/book/v3/adding-config-provider.md @@ -1,10 +1,10 @@ # 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, eg.: \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 `Laminas\Log\Logger::class`from the container, dot-log.my_logger should be requested (or just `my_logger` if using laminas-log) +* 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/v3/configuring-writer.md b/docs/book/v3/configuring-writer.md index c76b6e9..a9ed716 100644 --- a/docs/book/v3/configuring-writer.md +++ b/docs/book/v3/configuring-writer.md @@ -6,8 +6,7 @@ A writer is an object that inherits from `Laminas\Log\Writer\AbstractWriter`. A ## Writing to a file (stream) -It is possible separate logs into multiple files using writers and filters. -For example *warnings.log*, *errors.log*, *all_messages.log*. +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` @@ -32,15 +31,16 @@ return [ ``` * 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 `name` key is a developer-provided name for that writer, the writer name key is **mandatory**. -The writer priority key is not affecting the errors that are written, it is a way to organize writers, for example: +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 -It is the most important to write in the file, the sql or e-mail are more probably fail because the servers can be external and offline, the file is on the same server. +* 1 - FILE +* 2 - SQL +* 3 - E-mail -The writer priority key is optional. +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. -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. +The `priority` key is optional. + +The key `stream` is required only if writing into streams/files. diff --git a/docs/book/v3/example-with-formatter.md b/docs/book/v3/example-with-formatter.md index fba6b85..ed8b278 100644 --- a/docs/book/v3/example-with-formatter.md +++ b/docs/book/v3/example-with-formatter.md @@ -1,10 +1,10 @@ # 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 +* 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 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/docs/book/v3/filtering-log-messages.md b/docs/book/v3/filtering-log-messages.md index 2e6326d..8171d32 100644 --- a/docs/book/v3/filtering-log-messages.md +++ b/docs/book/v3/filtering-log-messages.md @@ -1,16 +1,25 @@ # Filtering log messages -As per PSR-3 document. +The following conforms to the `PSR-3: Logger Interface` document. -The log levels are: emergency (0), alert (1), critical (2), error (3), warn (4), notice (5), info (6), debug (7) (in order of priority/importance) +The log levels are in order of priority/importance: -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. +* 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 more critical) are logged in `/log/important_messages.log` +* Third Example: `WarningOrHigherWriter` - All important messages (`warnings` or critical) are logged in `/log/important_messages.log` ```php 'priority', 'options' => [ // note, the smaller the priority, the more important is the message - // 0 - emergency, 1 - alert, 2- error, 3 - warn. .etc + // 0 - emergency, 1 - alert, 2- error, 3 - warn etc. 'operator' => '<=', 'priority' => \Laminas\Log\Logger::WARN, ], @@ -81,10 +90,8 @@ return [ 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 was been added to illustrate how to explicitly allow all messages. +IMPORTANT NOTE: the operator for more important messages is `<=`, this is because the number representation is smaller for a more important message type. -It was added opposite to the others just to demonstrate the other operator is also an option. +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/v3/formatting-messages.md b/docs/book/v3/formatting-messages.md index 706877c..c0b028a 100644 --- a/docs/book/v3/formatting-messages.md +++ b/docs/book/v3/formatting-messages.md @@ -1,18 +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 a better readability, these arrays can be serialized. - -Laminas Log provides String formatting, XML, JSON and FirePHP formatting. +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 - options to pass to the formatter constructor if required +* name - the formatter class (it must implement `Laminas\Log\Formatter\FormatterInterface`) +* options - passed to the formatter constructor if required -The following formats the message as JSON data: +The following snippet formats the message as JSON data: -'formatter' => [ -'name' => \Laminas\Log\Formatter\Json::class, -], + 'formatter' => [ + 'name' => \Laminas\Log\Formatter\Json::class, + ], diff --git a/docs/book/v3/grouping-log-files-by-date.md b/docs/book/v3/grouping-log-files-by-date.md index 6cf70b4..7437b4e 100644 --- a/docs/book/v3/grouping-log-files-by-date.md +++ b/docs/book/v3/grouping-log-files-by-date.md @@ -1,10 +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, automatically grouping your logs by day, week, month, year etc. + +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 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) +* `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). From a16910755aa72e1a15e7b7c7c24afb5ccbdeb13a Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 17 May 2024 13:43:39 +0300 Subject: [PATCH 2/2] updated docs --- docs/book/v3/adding-config-provider.md | 8 ++++---- docs/book/v3/filtering-log-messages.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/book/v3/adding-config-provider.md b/docs/book/v3/adding-config-provider.md index eeb75d2..e591844 100644 --- a/docs/book/v3/adding-config-provider.md +++ b/docs/book/v3/adding-config-provider.md @@ -1,10 +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. + * 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/v3/filtering-log-messages.md b/docs/book/v3/filtering-log-messages.md index 8171d32..32c185f 100644 --- a/docs/book/v3/filtering-log-messages.md +++ b/docs/book/v3/filtering-log-messages.md @@ -2,7 +2,7 @@ The following conforms to the `PSR-3: Logger Interface` document. -The log levels are in order of priority/importance: +The log levels are in order of priority/importance: * emergency (0) * alert (1)