diff --git a/CHANGELOG.md b/CHANGELOG.md index d7839c00..1fd9ce72 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 2971cc50..a63065b8 100644 --- a/README.md +++ b/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']) + ), ); ``` diff --git a/src/ContextProvider/CommonContextProvider.php b/src/ContextProvider/CommonContextProvider.php new file mode 100644 index 00000000..9b08b7ae --- /dev/null +++ b/src/ContextProvider/CommonContextProvider.php @@ -0,0 +1,21 @@ +data; + } +} diff --git a/src/ContextProvider/ContextProvider.php b/src/ContextProvider/SystemContextProvider.php similarity index 98% rename from src/ContextProvider/ContextProvider.php rename to src/ContextProvider/SystemContextProvider.php index 11cd4424..4a4a5dde 100644 --- a/src/ContextProvider/ContextProvider.php +++ b/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. diff --git a/src/Logger.php b/src/Logger.php index b99106f7..4d4d755a 100644 --- a/src/Logger.php +++ b/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,7 +79,7 @@ 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( @@ -87,7 +87,7 @@ public function __construct( ?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.' ); diff --git a/src/Target.php b/src/Target.php index d2cb7d72..efef680d 100644 --- a/src/Target.php +++ b/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 { diff --git a/tests/ContextProvider/CommonContextProviderTest.php b/tests/ContextProvider/CommonContextProviderTest.php new file mode 100644 index 00000000..97d47949 --- /dev/null +++ b/tests/ContextProvider/CommonContextProviderTest.php @@ -0,0 +1,20 @@ + 'value']; + + $provider = new CommonContextProvider($data); + + $this->assertSame($data, $provider->getContext()); + } +}