From 03d503c2617c3064878ef4abb0c04426b53bebd0 Mon Sep 17 00:00:00 2001 From: Dustin Wilson Date: Mon, 3 Apr 2023 23:49:36 -0500 Subject: [PATCH] Update README --- README.md | 2 ++ tests/cases/TestLogger.php | 4 +--- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c80c982..f0516a8 100644 --- a/README.md +++ b/README.md @@ -18,3 +18,5 @@ This library attempts what we're calling an "opinionated" implementation of PSR- 2. In [section 1.2][b] of the specification it describes an optional feature, placeholders, and requires the implementor to write code to parse out and replace placeholders using a syntax and a method that's not present anywhere else in the entirety of PHP. _Logger_ won't support this feature because a logging library's place is to log messages and not to interpolate template strings. A separate library or a built-in function such as `sprintf` should be used instead. _Logger_ provides a way to transform messages that can be used to hook in a preferred interpolation method if desired, though. 3. The specification in [section 1.3][d] also specifies that if an `Exception` object is passed in the `$context` parameter it must be within an `exception` key. This makes sense, but curiously there's nary a mention of what to do with an `Error` object. They've existed since PHP 7 and can be thrown just like exceptions. _Logger_ will accept any `Throwable` in the `exception` key, but at present does nothing with it. Theoretically future handlers could be written to take advantage of it for structured data. + +PSR-3 is a deeply flawed specification that is vague in many aspects it shouldn't be and is badly designed in others; sometimes it's both. Section 1.3 in the first paragraph states categorically that implementors must not trigger a warning when errant data is in the `$context` array and treat it with _as much lenience as possible_. It then states in the following paragraph that if an exception is present in the context data it *must* be in the `exception` key and that implementors *must* verify the `exception` key. This appears to be contradictory. You can't verify the `exception` key without triggering an error or exception when it's wrong. The user should be notified that they made a mistake; it's bad design otherwise. We at present do nothing. Since the `exception` key isn't currently utilized within _Logger_ we've left the issue open. \ No newline at end of file diff --git a/tests/cases/TestLogger.php b/tests/cases/TestLogger.php index fe8c973..9f452f2 100644 --- a/tests/cases/TestLogger.php +++ b/tests/cases/TestLogger.php @@ -57,9 +57,7 @@ class TestLogger extends \PHPUnit\Framework\TestCase { $regex = '/^' . (new \DateTimeImmutable())->format('M d') . ' \d{2}:\d{2}:\d{2} ook ' . strtoupper($levelName) . ' Ook!\n/'; $this->assertEquals(1, preg_match($regex, $o)); - // Try it again with Level enum, and for shits and giggles test removal - // of errant throwables in context - $l->log(constant(sprintf('%s::%s', Level::class, ucfirst($levelName))), 'Ook!', [ 'ook' => new \Exception('ook'), 'exception' => 'ook', 'eek' => 'Eek!' ]); + $l->log(constant(sprintf('%s::%s', Level::class, ucfirst($levelName))), 'Ook!'); rewind($s); $o = stream_get_contents($s); $this->assertEquals(1, preg_match($regex, $o));