Add CommonContextProvider + Deprecate common context in Target

CHANGELOG.md

@@ -9,15 +9,15 @@
 - Bug #98: Fix error on formatting trace, when it doesn't contain "file" and "line" (@vjik)
 - New #108: Support of nested values in message templates' variables, e. g. `{foo.bar}` (@vjik)
 - Bug #89: Fix error on parse messages, that contains variables that cannot cast to a string (@vjik)
-- New #109: Add context provider (@vjik)
+- New #109, #113, #116: Add context providers (@vjik)
 - Chg #109: Deprecate `Logger` methods `setTraceLevel()` and `setExcludedTracePaths()` in favor of context provider
   usage (@vjik)
 - New #111: Add `DateTime` and `DateTimeImmutable` support as time in log context (@vjik)
 - New #112: Add `Message::category()` method and `Message::DEFAULT_CATEGORY` constant, deprecate
   `CategoryFilter::DEFAULT` in favor it (@vjik)
 - New #113: Add `Message::trace()` method (@vjik)
-- Enh #113: Remove unnecessary `unset` call in `ContextProvider` (@vjik)
 - New #114: Add `Message::time()` method (@vjik)
+- Chg #116: Deprecate methods `setCommonContext()` and `getCommonContext()` in `Target` class (@vjik)
 
 ## 2.0.0 May 22, 2022
 

README.md

@@ -99,14 +99,24 @@ in `Logger` constructor:
 $logger = new \Yiisoft\Log\Logger(contextProvider: $myContextProvider);
 ```
 
-By default, the logger uses built-in `Yiisoft\Log\ContextProvider\ContextProvider` that added following data to context:
+Out of the box, the following context providers are available:
+
+- `SystemContextProvider` — adds system information (time, memory usage, trace, default category);
+- `CommonContextProvider` — adds common data;
+- `CompositeContextProvider` — allows combining multiple context providers.
+
+By default, the logger uses built-in `SystemContextProvider`.
+
+#### `SystemContextProvider`
+
+`SystemContextProvider` added following data to context:
 
 - `time` — current Unix timestamp with microseconds (float value);
 - `trace` — array of call stack information;
 - `memory` — memory usage in bytes.
 - `category` — category of the log message (always "application").
 
-`Yiisoft\Log\ContextProvider\ContextProvider` constructor parameters:
+`Yiisoft\Log\ContextProvider\SystemContextProvider` constructor parameters:
 
 - `traceLevel` — how much call stack information (file name and line number) should be logged for each
   log message. If it is greater than 0, at most that number of call stacks will be logged. Note that only
@@ -117,12 +127,37 @@ Example of custom parameters' usage:
 
 ```php
 $logger = new \Yiisoft\Log\Logger(
-    contextProvider: new Yiisoft\Log\ContextProvider\ContextProvider(
+    contextProvider: new Yiisoft\Log\ContextProvider\SystemContextProvider(
         traceLevel: 3,
         excludedTracePaths: [
             '/vendor/yiisoft/di',
         ],
-    )
+    ),
+);
+```
+
+#### `CommonContextProvider`
+
+`CommonContextProvider` allows to add additional common information to the log context. For example:
+
+```php
+$logger = new \Yiisoft\Log\Logger(
+    contextProvider: new Yiisoft\Log\ContextProvider\CommonContextProvider([
+       'environment' => 'production',
+    ]),
+);
+```
+
+#### `CompositeContextProvider`
+
+`CompositeContextProvider` allows to combine multiple context providers into one. For example:
+
+```php
+$logger = new \Yiisoft\Log\Logger(
+    contextProvider: new Yiisoft\Log\ContextProvider\CompositeContextProvider(
+        new Yiisoft\Log\ContextProvider\SystemContextProvider(),
+        new Yiisoft\Log\ContextProvider\CommonContextProvider(['environment' => 'production'])
+    ),
 );
 ```
 

src/ContextProvider/CommonContextProvider.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Log\ContextProvider;
+
+/**
+ * `CommonContextProvider` is used to add additional information to the log context.
+  */
+final class CommonContextProvider implements ContextProviderInterface
+{
+    public function __construct(
+        private array $data,
+    ) {
+    }
+
+    public function getContext(): array
+    {
+        return $this->data;
+    }
+}

src/ContextProvider/ContextProvider.php → src/ContextProvider/SystemContextProvider.php

@@ -10,7 +10,7 @@
 /**
  * @psalm-import-type TraceItem from Message
  */
-final class ContextProvider implements ContextProviderInterface
+final class SystemContextProvider implements ContextProviderInterface
 {
     /**
      * @var string[] $excludedTracePaths Array of paths to exclude from tracing when tracing is enabled.

src/Logger.php

@@ -11,7 +11,7 @@
 use RuntimeException;
 use Stringable;
 use Throwable;
-use Yiisoft\Log\ContextProvider\ContextProvider;
+use Yiisoft\Log\ContextProvider\SystemContextProvider;
 use Yiisoft\Log\ContextProvider\ContextProviderInterface;
 
 use function count;
@@ -79,15 +79,15 @@ final class Logger implements LoggerInterface
      * Initializes the logger by registering {@see Logger::flush()} as a shutdown function.
      *
      * @param Target[] $targets The log targets.
-     * @param ContextProviderInterface|null $contextProvider The context provider. If null, {@see ContextProvider} with
+     * @param ContextProviderInterface|null $contextProvider The context provider. If null, {@see SystemContextProvider} with
      * default parameters will be used.
      */
     public function __construct(
         array $targets = [],
         ?ContextProviderInterface $contextProvider = null,
     ) {
         $this->setTargets($targets);
-        $this->contextProvider = $contextProvider ?? new ContextProvider();
+        $this->contextProvider = $contextProvider ?? new SystemContextProvider();
 
         register_shutdown_function(function () {
             // make regular flush before other shutdown functions, which allows session data collection and so on
@@ -185,11 +185,11 @@ public function setFlushInterval(int $flushInterval): self
      * @param int $traceLevel The number of call stack information.
      *
      * @deprecated since 2.1, to be removed in 3.0 version. Use {@see self::$contextProvider}
-     * and {@see ContextProvider::setTraceLevel()} instead.
+     * and {@see SystemContextProvider::setTraceLevel()} instead.
      */
     public function setTraceLevel(int $traceLevel): self
     {
-        if (!$this->contextProvider instanceof ContextProvider) {
+        if (!$this->contextProvider instanceof SystemContextProvider) {
             throw new RuntimeException(
                 '"Logger::setTraceLevel()" is unavailable when using a custom context provider.'
             );
@@ -207,11 +207,11 @@ public function setTraceLevel(int $traceLevel): self
      * @throws InvalidArgumentException for non-string values.
      *
      * @deprecated since 2.1, to be removed in 3.0 version. Use {@see self::$contextProvider}
-     * and {@see ContextProvider::setExcludedTracePaths()} instead.
+     * and {@see SystemContextProvider::setExcludedTracePaths()} instead.
      */
     public function setExcludedTracePaths(array $excludedTracePaths): self
     {
-        if (!$this->contextProvider instanceof ContextProvider) {
+        if (!$this->contextProvider instanceof SystemContextProvider) {
             throw new RuntimeException(
                 '"Logger::setExcludedTracePaths()" is unavailable when using a custom context provider.'
             );

src/Target.php

@@ -6,6 +6,7 @@
 
 use InvalidArgumentException;
 use RuntimeException;
+use Yiisoft\Log\ContextProvider\CommonContextProvider;
 use Yiisoft\Log\Message\CategoryFilter;
 use Yiisoft\Log\Message\Formatter;
 
@@ -176,6 +177,8 @@ public function setLevels(array $levels): self
      * @return self
      *
      * @see Target::$commonContext
+     *
+     * @deprecated since 2.1, to be removed in 3.0. Use {@see CommonContextProvider} instead.
      */
     public function setCommonContext(array $commonContext): self
     {
@@ -359,6 +362,8 @@ protected function formatMessages(string $separator = ''): string
      * Gets a user parameters in the `key => value` format that should be logged in a each message.
      *
      * @return array The user parameters in the `key => value` format.
+     *
+     * @deprecated since 2.1, to be removed in 3.0. Use {@see CommonContextProvider} instead.
      */
     protected function getCommonContext(): array
     {

tests/ContextProvider/CommonContextProviderTest.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Log\Tests\ContextProvider;
+
+use PHPUnit\Framework\TestCase;
+use Yiisoft\Log\ContextProvider\CommonContextProvider;
+
+final class CommonContextProviderTest extends TestCase
+{
+    public function testBase(): void
+    {
+        $data = ['key' => 'value'];
+
+        $provider = new CommonContextProvider($data);
+
+        $this->assertSame($data, $provider->getContext());
+    }
+}