csfix + update docs

Author: timdev

README.md

@@ -123,10 +123,6 @@ class SomeService
 - [ ] Make MonologStackLogger implement Monolog's ResettableInterface? 
 - [ ] Consider how this might play with Laravel, the insanely popular PHP 
       framework that I do my best to avoid. 😜
-- [ ] Track what's going on with PSR-3 v2/v3 as well as monolog and 
-      laminas-log. Eventually, we should rely on the updated + better-typed  
-      versions of the spec. We may need to drop the laminas-log test code since
-      laminas-log will likely always require psr/[email protected]
 
       
 

composer.json

@@ -50,22 +50,21 @@
         "cs-check": "phpcs",
         "cs-fix": "phpcbf",
         "dev": "@dev:qa",
-        "dev:analyze": "phpstan",
+        "dev:analyze": "phpstan analyze",
         "dev:coverage": "XDEBUG_MODE=coverage phpunit --coverage-text --colors=always",
         "dev:coverage:html": "XDEBUG_MODE=coverage phpunit --coverage-html build/coverage && echo '\\nCoverage Report: build/coverage/index.html'",
-        "dev:cs": "phpcs",
-        "dev:cs:fix": "phpcbf",
+        "dev:cs": "ecs check",
+        "dev:cs:fix": "ecs check --fix",
         "dev:qa": [
             "@dev:analyze",
             "@dev:test",
             "@dev:cs"
         ],
-        "dev:test": "phpunit --testdox --color=always",
-        "test": "XDEBUG_MODE=coverage phpunit --coverage-text --colors=always --testdox"
+        "dev:test": "phpunit --testdox --color=always"
     },
     "scripts-descriptions": {
         "dev": "Shortcut for dev:qa.",
-        "dev:analyze": "Run static analysis with psalm.",
+        "dev:analyze": "Run static analysis with phpstan.",
         "dev:coverage": "Report unit test coverage with output in the terminal.",
         "dev:coverage:html": "Generate unit test coverage report.",
         "dev:cs": "Run code style checks.",

ecs.php

@@ -0,0 +1,46 @@
+<?php declare(strict_types=1);
+
+use Symplify\EasyCodingStandard\Config\ECSConfig;
+
+return ECSConfig::configure()
+    ->withPaths([
+        __DIR__ . '/src',
+        __DIR__ . '/tests',
+    ])
+    ->withRootFiles()
+    ->withRules([
+        \PhpCsFixer\Fixer\Strict\DeclareStrictTypesFixer::class,
+        \PhpCsFixer\Fixer\Import\NoUnusedImportsFixer::class,
+    ])
+    ->withPhpCsFixerSets(perCS20: true)
+    ->withPreparedSets(psr12: true, common: true, symplify: true)
+    ->withConfiguredRule(PhpCsFixer\Fixer\Phpdoc\PhpdocLineSpanFixer::class, [
+        'property' => 'single',
+        'method'   => 'single',
+        'const'    => 'single',
+    ])
+    ->withConfiguredRule(PhpCsFixer\Fixer\Operator\BinaryOperatorSpacesFixer::class, [
+        'operators' => [
+            '=>' => 'align',
+            '='  => 'align',
+        ],
+    ])
+    ->withConfiguredRule(PhpCsFixer\Fixer\Phpdoc\PhpdocLineSpanFixer::class, [
+        'const'    => 'single',
+        'method'   => 'single',
+        'property' => 'single',
+    ])
+    ->withConfiguredRule(Symplify\CodingStandard\Fixer\LineLength\LineLengthFixer::class, [
+        'inline_short_lines' => false,
+    ])
+    ->withSkip([
+        Symplify\CodingStandard\Fixer\ArrayNotation\ArrayOpenerAndCloserNewlineFixer::class,
+
+        // <?php declare(strict_types=1); doesn't need to take up three or four lines:
+        PhpCsFixer\Fixer\PhpTag\BlankLineAfterOpeningTagFixer::class,
+        PhpCsFixer\Fixer\PhpTag\LinebreakAfterOpeningTagFixer::class,
+
+        Symplify\CodingStandard\Fixer\ArrayNotation\StandaloneLineInMultilineArrayFixer::class,
+        Symplify\CodingStandard\Fixer\ArrayNotation\ArrayListItemNewlineFixer::class,
+    ])
+;

src/MonologStackLogger.php

@@ -1,12 +1,9 @@
-<?php
-
-declare(strict_types=1);
+<?php declare(strict_types=1);
 
 namespace TimDev\StackLogger;
 
 use Monolog\Handler\NullHandler;
 use Monolog\Logger as MonologLogger;
-use Psr\Log\LoggerInterface as PsrInterface;
 
 /**
  * Extends Psr3Logger to provide a monolog-like withName() method.
@@ -24,7 +21,7 @@ public function withName(string $name): static
     {
         // this works, but requires WrappedPSR3::$logger to be non-private.
         // Is there a better way?
-        $new = clone $this;
+        $new         = clone $this;
         $new->logger = $this->logger->withName($name);
         $new->parent = $this;
         return $new;

src/Psr3StackLogger.php

@@ -1,13 +1,10 @@
-<?php
-
-declare(strict_types=1);
+<?php declare(strict_types=1);
 
 namespace TimDev\StackLogger;
 
 use Psr\Log\LoggerInterface as PsrInterface;
 use Psr\Log\LoggerTrait;
 use Psr\Log\NullLogger;
-use function PHPStan\dumpType;
 
 /**
  * Implements LoggerInterface by wrapping a PSR3 logger.
@@ -21,7 +18,7 @@ class Psr3StackLogger implements StackLogger
     /** @var L */
     protected PsrInterface $logger;
 
-    /** @var static  */
+    /** @var static */
     protected ?StackLogger $parent = null;
 
     /** @var array<mixed> */
@@ -39,23 +36,16 @@ public function getWrapped(): PsrInterface
         return $this->logger;
     }
 
-    /** @param L $logger */
-    final protected function setWrapped(PsrInterface $logger): void
-    {
-        $this->logger = $logger;
-    }
-
     /**
      * Context Handling
      *
      * @param array<string, mixed> $context
-     * @return static
      */
     #[\Override]
     public function withContext(array $context = []): static
     {
-        $child = clone $this;
-        $child->parent = $this;
+        $child          = clone $this;
+        $child->parent  = $this;
         $child->context = $context;
         return $child;
     }
@@ -71,6 +61,28 @@ public function addContext(array $context): static
         return $this;
     }
 
+    /* PSR3 Implementation, wrapping our wrapped instance. */
+
+    #[\Override]
+    public function log($level, string|\Stringable $message, array $context = []): void
+    {
+        assert(is_string($level) || is_int($level));
+        $context = $this->processContext($context);
+        $this->logger->log($level, $message, $context);
+    }
+
+    public static function makeNullLogger(): StackLogger
+    {
+        $instance = new NullLogger();
+        return new self($instance);
+    }
+
+    /** @param L $logger */
+    final protected function setWrapped(PsrInterface $logger): void
+    {
+        $this->logger = $logger;
+    }
+
     /**
      * Merges $context on top of the instances accumulated context, and
      * processes any callable elements in the final context.
@@ -83,10 +95,7 @@ protected function processContext(array $context = []): array
         $context = array_merge($this->mergedContext(), $context);
 
         // handle any callables in final context.
-        return array_map(
-            static fn($c): mixed => is_callable($c) ? $c($context) : $c,
-            $context
-        );
+        return array_map(static fn($c): mixed => is_callable($c) ? $c($context) : $c, $context);
     }
 
     /**
@@ -95,30 +104,12 @@ protected function processContext(array $context = []): array
      */
     protected function contextToMerge(): array
     {
-        return [
-            ... ($this->parent !== null)  ? $this->parent->contextToMerge() : [],
-            $this->context
-        ];
+        return [...($this->parent !== null) ? $this->parent->contextToMerge() : [], $this->context];
     }
 
     /** @return array<mixed> */
     protected function mergedContext(): array
     {
         return array_merge(...$this->contextToMerge());
     }
-
-    /* PSR3 Implementation, wrapping our wrapped instance. */
-
-    #[\Override]
-    public function log($level, string|\Stringable $message, array $context = []): void
-    {
-        assert(is_string($level) || is_int($level));
-        $context = $this->processContext($context);
-        $this->logger->log($level, $message, $context);
-    }
-    public static function makeNullLogger(): StackLogger
-    {
-        $instance = new NullLogger();
-        return new self($instance);
-    }
 }

src/StackLogger.php

@@ -1,6 +1,4 @@
-<?php
-
-declare(strict_types=1);
+<?php declare(strict_types=1);
 
 namespace TimDev\StackLogger;
 

src/WrappingStackLogger.php

@@ -1,6 +1,4 @@
-<?php
-
-declare(strict_types=1);
+<?php declare(strict_types=1);
 
 namespace TimDev\StackLogger;
 

tests/BaseTestCase.php

@@ -1,11 +1,8 @@
-<?php
-
-declare(strict_types=1);
+<?php declare(strict_types=1);
 
 namespace TimDev\StackLogger\Test;
 
 use PHPUnit\Framework\TestCase;
-use TimDev\StackLogger\StackLogger;
 use TimDev\StackLogger\Test\Support\TestStackLogger;
 
 /**
@@ -17,12 +14,10 @@
  */
 abstract class BaseTestCase extends TestCase
 {
-    abstract protected function makeTestSubject(): TestStackLogger;
-
     private TestStackLogger $log;
 
     #[\Override]
-    public function setUp(): void
+    protected function setUp(): void
     {
         $this->log = $this->makeTestSubject();
     }
@@ -50,10 +45,7 @@ public function testAddsContext(): void
 
         $this->log
             ->addContext(['even more' => 'context'])
-            ->warning(
-                'This message should get four context elements.',
-                ['foo' => 'bar']
-            );
+            ->warning('This message should get four context elements.', ['foo' => 'bar']);
         self::assertEquals(4, $this->log->contextCountAt(2));
 
         $this->log->debug('Back to three!');
@@ -70,7 +62,7 @@ public function testCreateChildWithContext(): void
 
     public function testAccumulatesContext(): void
     {
-        $log = $this->log->withContext(['initial' => 'context']);
+        $log   = $this->log->withContext(['initial' => 'context']);
         $child = $log->withContext(['more' => 'context']);
 
         // $child should have two context items.
@@ -87,10 +79,7 @@ public function testAccumulatesContext(): void
         $log->info('I should have one context item (on my second record)');
 
         self::assertCount(1, $log->contextAt(1));
-        self::assertEquals(
-            ['initial'],
-            $log->contextKeysAt(1)
-        );
+        self::assertEquals(['initial'], $log->contextKeysAt(1));
     }
 
     public function testMergesContext(): void
@@ -101,30 +90,24 @@ public function testMergesContext(): void
         $log
             ->withContext(['a' => 'Allison', 'b' => 'Bob'])
             ->emergency('Allison and Bruno', ['b' => 'Bruno']);
-        self::assertEquals(
-            ['Allison', 'Bruno'],
-            $this->log->contextValuesAt(0)
-        );
+        self::assertEquals(['Allison', 'Bruno'], $this->log->contextValuesAt(0));
 
         // But original logger should still have (only) Alice.
         $log->critical('Alice alone.');
-        self::assertEquals(
-            ['a' => 'Alice'],
-            $this->log->contextAt(1)
-        );
+        self::assertEquals(['a' => 'Alice'], $this->log->contextAt(1));
     }
 
     public function testInvokesCallables(): void
     {
         $logger = $this->log;
-        $child = $logger->withContext(
+        $child  = $logger->withContext(
             [
                 // A callable context element that returns the number of
                 // elements in the record's context.
                 'counter' => function (array $ctx) {
                     return count($ctx);
-                }
-            ]
+                },
+            ],
         );
         $child->notice('Only one context element, the result of the callable.');
         self::assertEquals(1, $child->contextAt(0)['counter']);
@@ -133,10 +116,10 @@ public function testInvokesCallables(): void
         $child->warning('A log with three context items.', ['Third' => 'Context Item']);
         self::assertEquals(
             $child->contextCountAt(1),          // === 3
-            $child->contextAt(1)['counter']
+            $child->contextAt(1)['counter'],
         );
 
-        $start = microtime(true);
+        $start  = microtime(true);
         $child2 = $logger->withContext(['elapsed_micros' => fn() => 1000000 * (microtime(true) - $start)]);
         usleep(1000);
         $child2->alert('At least 1000 μ-sec have passed.');
@@ -149,15 +132,16 @@ public function testInvokesCallables(): void
      */
     public function testLongChain(): void
     {
-        $logger = $this->log;
+        $logger     = $this->log;
         $numLoggers = 20;
         foreach (range(1, $numLoggers) as $i) {
             $logger = $logger->withContext(["gen{$i}" => $i]);
         }
-        $logger->withContext(["count" => fn(array $ctx) => count($ctx)]);
-        $logger->error("I come from a long lineage", ['final' => 'I should be the 21st context element']);
+        $logger->withContext(['count' => fn(array $ctx) => count($ctx)]);
+        $logger->error('I come from a long lineage', ['final' => 'I should be the 21st context element']);
         self::assertIsIterable($logger->recordAt(0)['context']);
         self::assertCount($numLoggers + 1, $logger->recordAt(0)['context']);
     }
 
+    abstract protected function makeTestSubject(): TestStackLogger;
 }