Merge pull request #43 from dotkernel/issue-40

updated docs

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).

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.

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
 <?php
@@ -39,30 +39,3 @@ return [
     ],
 ];
 ```
-
-## Usage
-
-Basic usage of the logger is illustraded below.
-
-The messages are written to see which logs are written and which are not written.
-
-```php
-use Laminas\Log\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()');
-```

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
 <?php
@@ -64,7 +73,7 @@ return [
                                     'name' => '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/

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,
+    ],

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).