Skip to content

Commit

Permalink
updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Sergiu committed Aug 28, 2024
1 parent a795c4d commit 3cf57c6
Show file tree
Hide file tree
Showing 13 changed files with 274 additions and 13 deletions.
2 changes: 1 addition & 1 deletion docs/book/v3/configuring-writer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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',
],
Expand Down
6 changes: 3 additions & 3 deletions docs/book/v3/example-with-formatter.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
],
],
],
Expand Down
12 changes: 6 additions & 6 deletions docs/book/v3/filtering-log-messages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,15 @@ return [
'writers' => [
'FileWriter' => [
'name' => 'FileWriter',
'priority' => \Dot\Log\Manager\Logger::ALERT,
'priority' => \Laminas\Log\Logger::ALERT,
'options' => [
'stream' => __DIR__ . '/../../log/dk.log',
'filters' => [
'allMessages' => [
'name' => 'priority',
'options' => [
'operator' => '>=',
'priority' => \Dot\Log\Manager\Logger::EMERG,
'priority' => \Laminas\Log\Logger::EMERG,
]
],
],
Expand All @@ -48,15 +48,15 @@ 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' => [
'warningOnly' => [
'name' => 'priority',
'options' => [
'operator' => '==',
'priority' => \Dot\Log\Manager\Logger::WARN,
'priority' => \Laminas\Log\Logger::WARN,
],
],
],
Expand All @@ -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' => [
Expand All @@ -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,
],
],
],
Expand Down
2 changes: 1 addition & 1 deletion docs/book/v3/usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
```

...
Expand Down
10 changes: 10 additions & 0 deletions docs/book/v4/adding-config-provider.md
View file
Original file line number Diff line number Diff line change
@@ -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).
46 changes: 46 additions & 0 deletions docs/book/v4/configuring-writer.md
View file
Original file line number Diff line number Diff line change
@@ -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.
41 changes: 41 additions & 0 deletions docs/book/v4/example-with-formatter.md
View file
Original file line number Diff line number Diff line change
@@ -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
<?php
return [
'dot_log' => [
'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,
],
],
],
],
],
],
],
];
```
97 changes: 97 additions & 0 deletions docs/book/v4/filtering-log-messages.md
View file
Original file line number Diff line number Diff line change
@@ -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
<?php

return [
'dot_log' => [
'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/
14 changes: 14 additions & 0 deletions docs/book/v4/formatting-messages.md
View file
Original file line number Diff line number Diff line change
@@ -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,
],
12 changes: 12 additions & 0 deletions docs/book/v4/grouping-log-files-by-date.md
View file
Original file line number Diff line number Diff line change
@@ -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).
5 changes: 5 additions & 0 deletions docs/book/v4/overview.md
View file
Original file line number Diff line number Diff line change
@@ -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)
26 changes: 26 additions & 0 deletions docs/book/v4/usage.md
View file
Original file line number Diff line number Diff line change
@@ -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()');
```
14 changes: 12 additions & 2 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

0 comments on commit 3cf57c6

Please sign in to comment.