Skip to content

Commit

Permalink
updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
bidi47 committed Apr 4, 2024
1 parent d9ab25e commit 059067c
Showing 1 changed file with 10 additions and 13 deletions.
23 changes: 10 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ DotKernel log component extending and customizing

[![SymfonyInsight](https://insight.symfony.com/projects/287e81e8-b4fb-4452-bd8f-4f12c0ab1f76/big.svg)](https://insight.symfony.com/projects/287e81e8-b4fb-4452-bd8f-4f12c0ab1f76)


## Adding The Config Provider

Check failure on line 18 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## Adding The Config Provider"]

Check failure on line 18 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## Adding The Config Provider"]
* Enter config/config.php

Check failure on line 19 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Lists should be surrounded by blank lines [Context: "* Enter config/config.php"]

Check failure on line 19 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Lists should be surrounded by blank lines [Context: "* Enter config/config.php"]
* If there is no entry for the config provider below, add it:
Expand All @@ -27,16 +26,18 @@ DotKernel log component extending and customizing
- 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)

Check failure on line 26 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Unordered list style [Expected: asterisk; Actual: dash]

Check failure on line 26 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Unordered list indentation [Expected: 4; Actual: 2]

Check failure on line 26 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Unordered list style [Expected: asterisk; Actual: dash]

Check failure on line 26 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Unordered list indentation [Expected: 4; Actual: 2]

## 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' => [
Expand All @@ -56,10 +57,10 @@ 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 writer priority key is not affecting the errors that are written, it is a way to organize writers, for example:

1 - FILE
Expand All @@ -71,7 +72,6 @@ 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.


## Grouping log files by date

Check failure on line 75 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## Grouping log files by date"]

Check failure on line 75 in README.md

View workflow job for this annotation

GitHub Actions / ci / QA Checks (README Linting [8.1, latest], ubuntu-latest, laminas/laminas-continuous-integration-ac...

Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## 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.
Expand All @@ -81,7 +81,6 @@ Examples:

The full list of format specifiers is available [here](https://www.php.net/manual/en/datetime.format.php).


## Filtering log messages

As per PSR-3 document.
Expand All @@ -90,8 +89,8 @@ The log levels are: emergency (0), alert (1), critical (2), error (3), warn (4),

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`
Expand Down Expand Up @@ -171,8 +170,6 @@ The filter added on the first writer is equal to not setting a filter, but it wa

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/

## Formatting Messages
Expand All @@ -183,21 +180,17 @@ 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,
],


### Example with formatter

* The log is used through dot-log
Expand Down Expand Up @@ -243,13 +236,17 @@ 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');

Expand All @@ -266,9 +263,9 @@ $logger->log(Logger::NOTICE, 'NOTICE from log()');
```

Sources:

* https://docs.laminas.dev/laminas-log/
* https://docs.laminas.dev/laminas-log/writers/
* https://docs.laminas.dev/laminas-log/filters/

Extracted from [this article](https://www.dotkernel.com/dotkernel/logging-with-dot-log-in-mezzio-and-dotkernel)

0 comments on commit 059067c

Please sign in to comment.