Browse Source

Update README

main
Dustin Wilson 1 year ago
parent
commit
03d503c261
  1. 2
      README.md
  2. 4
      tests/cases/TestLogger.php

2
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.

4
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));

Loading…
Cancel
Save