From 38fd8efb89a7b0a893675b666ed40f154266f47a Mon Sep 17 00:00:00 2001
From: Jordi Boggiano <j.boggiano@seld.be>
Date: Mon, 9 May 2022 00:07:56 +0200
Subject: [PATCH] Update docs

---
 README.md                |  7 +++++--
 doc/01-usage.md          | 11 ++++++++---
 doc/04-extending.md      |  2 ++
 doc/message-structure.md | 21 ++++++++++++++-------
 4 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 8a431d7e..ac7ec324 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ $ composer require monolog/monolog
 ```php
 <?php
 
+use Monolog\Level;
 use Monolog\Logger;
 use Monolog\Handler\StreamHandler;
 
@@ -64,11 +65,13 @@ can also add your own there if you publish one.
 
 ### Requirements
 
-- Monolog `^2.0` works with PHP 7.2 or above, use Monolog `^1.25` for PHP 5.3+ support.
+- Monolog `^3.0` works with PHP 8.1 or above.
+- Monolog `^2.5` works with PHP 7.2 or above.
+- Monolog `^1.25` works with PHP 5.3 up to 8.1, but is not very maintained anymore and will not receive PHP support fixes anymore.
 
 ### Support
 
-Monolog 1.x support is somewhat limited at this point and only important fixes will be done. You should migrate to Monolog 2 where possible to benefit from all the latest features and fixes.
+Monolog 1.x support is somewhat limited at this point and only important fixes will be done. You should migrate to Monolog 2 or 3 where possible to benefit from all the latest features and fixes.
 
 ### Submitting bugs and feature requests
 
diff --git a/doc/01-usage.md b/doc/01-usage.md
index 54d7b36c..5cd82e1d 100644
--- a/doc/01-usage.md
+++ b/doc/01-usage.md
@@ -83,6 +83,7 @@ Here is a basic setup to log to a file and to firephp on the DEBUG level:
 ```php
 <?php
 
+use Monolog\Level;
 use Monolog\Logger;
 use Monolog\Handler\StreamHandler;
 use Monolog\Handler\FirePHPHandler;
@@ -147,7 +148,7 @@ $logger->pushProcessor(function ($record) {
 ```
 
 Monolog provides some built-in processors that can be used in your project.
-Look at the [dedicated chapter](https://github.com/Seldaek/monolog/blob/master/doc/02-handlers-formatters-processors.md#processors) for the list.
+Look at the [dedicated chapter](https://github.com/Seldaek/monolog/blob/main/doc/02-handlers-formatters-processors.md#processors) for the list.
 
 > Tip: processors can also be registered on a specific handler instead of
   the logger to apply only for this handler.
@@ -165,6 +166,7 @@ You can easily grep through the log files filtering this or that channel.
 ```php
 <?php
 
+use Monolog\Level;
 use Monolog\Logger;
 use Monolog\Handler\StreamHandler;
 use Monolog\Handler\FirePHPHandler;
@@ -196,7 +198,7 @@ As mentioned before, a *Formatter* is attached to a *Handler*, and as a general
 ```php
 $record->formatted
 ```
-field in the log record to store its formatted value. Again, this field depends on the implementation of the *Handler* but is a good idea to **stick into the good practices and conventions of the project**.
+property in the log record to store its formatted value.
 
 You can choose between predefined formatter classes or write your own (e.g. a multiline text file for human-readable output).
 
@@ -206,7 +208,10 @@ You can choose between predefined formatter classes or write your own (e.g. a mu
 >
 > This formatter, as its name might indicate, is able to return a lineal string representation of the log record provided.
 >
-> It is also capable to interpolate values from the log record, into the output format template used by the formatter to generate the final result, and in order to do it, you need to provide the log record values you are interested in, in the output template string using the form %value%, e.g: "'%context.foo% => %extra.foo%'" , in this example the values $record->context["foo"] and $record->extra["foo"] will be rendered as part of th final result.
+> It is also capable to interpolate values from the log record, into the output format template used by the formatter to generate
+> the final result, and in order to do it, you need to provide the log record values you are interested in, in the output template
+> string using the form %value%, e.g: "'%context.foo% => %extra.foo%'" , in this example the values `$record->context["foo"]`
+> and `$record->extra["foo"]` will be rendered as part of the final result.
 
 In the following example, we demonstrate how to:
 1. Create a `LineFormatter` instance and set a custom output format template.
diff --git a/doc/04-extending.md b/doc/04-extending.md
index 8d9d09a4..a57c70b7 100644
--- a/doc/04-extending.md
+++ b/doc/04-extending.md
@@ -21,6 +21,8 @@ abstract class provided by Monolog to keep things DRY.
 ```php
 <?php
 
+use Monolog\Level;
+use Monolog\LevelName;
 use Monolog\Logger;
 use Monolog\Handler\AbstractProcessingHandler;
 
diff --git a/doc/message-structure.md b/doc/message-structure.md
index 985e0faa..91508d41 100644
--- a/doc/message-structure.md
+++ b/doc/message-structure.md
@@ -1,18 +1,25 @@
 # Log message structure
 
-Within monolog log messages are passed around as arrays, for example to processors or handlers.
-The table below describes which keys are always available for every log message.
+Within monolog log messages are passed around as [Monolog\LogRecord](../src/Monolog/LogRecord.php) objects,
+for example to processors or handlers.
 
-key        | type                      | description
+The table below describes the properties available.
+
+property   | type                      | description
 -----------|---------------------------|-------------------------------------------------------------------------------
 message    | string                    | The log message. When the `PsrLogMessageProcessor` is used this string may contain placeholders that will be replaced by variables from the context, e.g., "User {username} logged in" with `['username' => 'John']` as context will be written as "User John logged in".
-level      | int                       | Severity of the log message. See log levels described in [01-usage.md](01-usage.md#log-levels).
-level_name | string                    | String representation of log level.
+level      | Monolog\Level case        | Severity of the log message. See log levels described in [01-usage.md](01-usage.md#log-levels).
+levelName  | Monolog\LevelName case    | String representation of log level.
 context    | array                     | Arbitrary data passed with the construction of the message. For example the username of the current user or their IP address.
 channel    | string                    | The channel this message was logged to. This is the name that was passed when the logger was created with `new Logger($channel)`.
 datetime   | Monolog\DateTimeImmutable | Date and time when the message was logged. Class extends `\DateTimeImmutable`.
 extra      | array                     | A placeholder array where processors can put additional data. Always available, but empty if there are no processors registered.
 
 At first glance `context` and `extra` look very similar, and they are in the sense that they both carry arbitrary data that is related to the log message somehow.
-The main difference is that `context` can be supplied in user land (it is the 3rd parameter to `Logger::addRecord()`) whereas `extra` is internal only and can be filled by processors.
-The reason processors write to `extra` and not to `context` is to prevent overriding any user-provided data in `context`.
+The main difference is that `context` can be supplied in user land (it is the 3rd parameter to `Psr\Log\LoggerInterface` methods) whereas `extra` is internal only
+and can be filled by processors. The reason processors write to `extra` and not to `context` is to prevent overriding any user-provided data in `context`.
+
+All properties except `extra` are read-only.
+
+> Note: For BC reasons with Monolog 1 and 2 which used arrays, `LogRecord` implements `ArrayAccess` so you can access the above properties
+> using `$record['message']` for example, with the notable exception of `levelName` which must be referred to as `level_name` for BC.