Issue 40

.github/workflows/docs-build.yml

@@ -0,0 +1,16 @@
+name: docs-build
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build Docs
+        uses: dotkernel/documentation-theme/github-actions/docs@main
+        env:
+          DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+## Supported Versions
+
+
+| Version | Supported          | PHP Version                                                                                        |
+|---------|--------------------|----------------------------------------------------------------------------------------------------|
+| 3.x     | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-log/3.4.7) |
+| <= 2.x  | :x:                |                                                                                                    |
+
+
+## Reporting Potential Security Issues
+
+If you have encountered a potential security vulnerability in this project,
+please report it to us at <[email protected]>. We will work with you to
+verify the vulnerability and patch it.
+
+When reporting issues, please provide the following information:
+
+- Component(s) affected
+- A description indicating how to reproduce the issue
+- A summary of the security vulnerability and impact
+
+We request that you contact us via the email address above and give the
+project contributors a chance to resolve the vulnerability and issue a new
+release prior to any public exposure; this helps protect the project's
+users, and provides them with a chance to upgrade and/or update in order to
+protect their applications.
+
+
+## Policy
+
+If we verify a reported security vulnerability, our policy is:
+
+- We will patch the current release branch, as well as the immediate prior minor
+  release branch.
+
+- After patching the release branches, we will immediately issue new security
+  fix releases for each patched release branch.
+

docs/book/v3/addingConfigProvider.md

@@ -0,0 +1,9 @@
+## 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 absctract 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)

docs/book/v3/configuringWriter.md

@@ -0,0 +1,43 @@
+## 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)
+It is possible 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' => \Laminas\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 priority key is not affecting 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.
+
+The writer priority 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.

docs/book/v3/exampleWithFormatter.md

@@ -0,0 +1,66 @@
+### 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
+<?php
+
+
+return [
+    'dot_log' => [
+        'loggers' => [
+            'my_logger' => [
+                'writers' => [
+                    'FileWriter' => [
+                        'name' => 'FileWriter',
+                        'priority' => \Laminas\Log\Logger::ALERT,
+                        'options' => [
+                            'stream' => __DIR__ . '/../../log/dk.log',
+                            // explicitly log all messages
+                            'filters' => [
+                                'allMessages' => [
+                                    'name' => 'priority',
+                                    'options' => [
+                                        'operator' => '>=',
+                                        'priority' => \Laminas\Log\Logger::EMERG,
+                                    ],
+                                ],
+                            ],
+                            'formatter' => [
+                                'name' => \Laminas\Log\Formatter\Json::class,
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+        ],
+    ],
+];
+```
+
+## 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/filteringLogMessages.md

@@ -0,0 +1,92 @@
+## 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 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.
+
+
+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
+<?php
+
+return [
+    'dot_log' => [
+        'loggers' => [
+            'my_logger' => [
+                'writers' => [
+                    'FileWriter' => [
+                        'name' => 'FileWriter',
+                        'priority' => \Laminas\Log\Logger::ALERT,
+                        'options' => [
+                            'stream' => __DIR__ . '/../../log/dk.log',
+                            'filters' => [
+                                'allMessages' => [
+                                    'name' => 'priority',
+                                    'options' => [
+                                        'operator' => '>=', 
+                                        'priority' => \Laminas\Log\Logger::EMERG,
+                                    ]
+                                ],
+                            ],
+                        ],
+                    ],
+                    // Only warnings
+                    'OnlyWarningsWriter' => [
+                        'name' => 'stream',
+                        'priority' => \Laminas\Log\Logger::ALERT,
+                        'options' => [
+                            'stream' => __DIR__ . '/../../log/warnings_only.log',
+                            'filters' => [
+                                'warningOnly' => [
+                                    'name' => 'priority',
+                                    'options' => [
+                                        'operator' => '==',
+                                        'priority' => \Laminas\Log\Logger::WARN,
+                                    ],
+                                ],
+                            ],
+                        ],
+                    ],
+                    // Warnings and more important messages
+                    'WarningOrHigherWriter' => [
+                        'name' => 'stream',
+                        'priority' => \Laminas\Log\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' => \Laminas\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 was 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.
+
+
+
+More examples on filters: https://docs.laminas.dev/laminas-log/filters/

docs/book/v3/formattingMessages.md

@@ -0,0 +1,21 @@
+## 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.
+
+
+
+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
+
+
+The following formats the message as JSON data:
+
+'formatter' => [
+'name' => \Laminas\Log\Formatter\Json::class,
+],

docs/book/v3/groupingLogFilesByDate.md

@@ -0,0 +1,8 @@
+## 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 [here](https://www.php.net/manual/en/datetime.format.php).

docs/book/v3/usage.md

@@ -0,0 +1,22 @@
+## 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()');
+```

mkdocs.yml

@@ -0,0 +1,21 @@
+docs_dir: docs/book
+site_dir: docs/html
+extra:
+  project: Packages
+  current_version: v3
+  versions:
+    - v3
+nav:
+  - Home: index.md
+  - v3:
+      - "Adding The Config Provider": v3/addingConfigProvider.md
+      - "Configuring the writer(s)": v3/configuringWriter.md
+      - "Grouping log files by date": v3/groupingLogFilesByDate.md
+      - "Filtering log messages": v3/filteringLogMessages.md
+      - "Formatting Messages": v3/formattingMessages.md
+      - "Usage": v3/usage.md
+site_name: dot-log
+site_description: "DotKernel log component extending and customizing"
+repo_url: "https://github.com/dotkernel/dot-log"
+plugins:
+  - search