From b4c50a17cf80a232f4d0f2550da8d51be02ef9c3 Mon Sep 17 00:00:00 2001 From: Sergei Predvoditelev Date: Tue, 2 Jul 2024 10:05:16 +0300 Subject: [PATCH 1/4] Add `CommonContextProvider` --- CHANGELOG.md | 2 +- src/ContextProvider/CommonContextProvider.php | 21 +++++++++++++++++++ .../CommonContextProviderTest.php | 20 ++++++++++++++++++ 3 files changed, 42 insertions(+), 1 deletion(-) create mode 100644 src/ContextProvider/CommonContextProvider.php create mode 100644 tests/ContextProvider/CommonContextProviderTest.php diff --git a/CHANGELOG.md b/CHANGELOG.md index d7839c00..01261013 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ - 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, #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) 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/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()); + } +} From af0f8ca488ad60a68fb8828376f5ad3e84771afb Mon Sep 17 00:00:00 2001 From: Sergei Predvoditelev Date: Tue, 2 Jul 2024 10:19:19 +0300 Subject: [PATCH 2/4] Rename `ContextProvider` to `SystemContextProvider` --- README.md | 43 +++++++++++++++++-- ...Provider.php => SystemContextProvider.php} | 2 +- src/Logger.php | 14 +++--- 3 files changed, 47 insertions(+), 12 deletions(-) rename src/ContextProvider/{ContextProvider.php => SystemContextProvider.php} (98%) 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/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.' ); From 35c8e36c84e153ce6913aed3b372589c31efb4cb Mon Sep 17 00:00:00 2001 From: Sergei Predvoditelev Date: Tue, 2 Jul 2024 10:22:11 +0300 Subject: [PATCH 3/4] Deprecate common context in target --- CHANGELOG.md | 1 + src/Target.php | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 01261013..2fb5aa85 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ - 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/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 { From 44035b0df91d87bbea9d838bad6466cf5a8c4abc Mon Sep 17 00:00:00 2001 From: Sergei Predvoditelev Date: Tue, 2 Jul 2024 10:40:47 +0300 Subject: [PATCH 4/4] Fix changelog --- CHANGELOG.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2fb5aa85..1fd9ce72 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,14 +9,13 @@ - 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, #116: Add context providers (@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)