Allow psr/log v2 and v3 dep (#392)

Co-authored-by: Michael Voříšek <mvorisek@mvorisek.cz>

Author: gowrav-vishwakarma

composer.json

@@ -32,7 +32,7 @@
     "require": {
         "php": ">=7.4 <8.4",
         "benmorel/weakmap-polyfill": "^0.4.0",
-        "psr/log": "^1.0",
+        "psr/log": "^1.0 || ^2.0 || ^3.0",
         "symfony/polyfill-php80": "^1.28",
         "symfony/polyfill-php81": "^1.28",
         "symfony/polyfill-php82": "^1.28",

docs/debug.md

@@ -28,8 +28,8 @@ described below:
 
 The design goal of Debug is to be able to display contextual debug information
 only when it's manually enabled. For instance, if you are having problem with
-user authentication, you should enable `$auth->debug()`. On other hand - if
-you wish to see persistence-related debug info, then `$db->debug()` will
+user authentication, you should enable `$auth->debug(true)`. On other hand - if
+you wish to see persistence-related debug info, then `$db->debug(true)` will
 enable that.
 
 Information logged through debug like this on any object that implements
@@ -48,7 +48,7 @@ most cases this will simply be ignored right away unless you manually enable
 debugging for the object:
 
 ```
-$obj1->debug(); // enable debugging
+$obj1->debug(true); // enable debugging
 $obj1->debug(false); // disable debugging
 $obj1->debug(true); // also enables debugging
 

src/DebugTrait.php

@@ -23,20 +23,34 @@ protected function _echoStderr(string $message): void
     }
 
     /**
-     * Send some info to debug stream.
+     * Logs with an arbitrary level.
      *
-     * @param bool|string  $message
-     * @param array<mixed> $context
+     * @param mixed              $level
+     * @param string|\Stringable $message
+     * @param array<mixed>       $context
+     */
+    public function log($level, $message, array $context = []): void
+    {
+        if (TraitUtil::hasAppScopeTrait($this) && $this->issetApp() && $this->getApp()->logger instanceof \Psr\Log\LoggerInterface) {
+            $this->getApp()->logger->log($level, $message, $context);
+        } else {
+            $this->_echoStderr($message . "\n");
+        }
+    }
+
+    /**
+     * Detailed debug information.
      *
-     * @return $this
+     * @param bool|string|\Stringable $message
+     * @param array<mixed>            $context
      */
-    public function debug($message = true, array $context = [])
+    public function debug($message, array $context = []): void
     {
         // using this to switch on/off the debug for this object
         if (is_bool($message)) {
             $this->debug = $message;
 
-            return $this;
+            return;
         }
 
         // if debug is enabled, then log it
@@ -46,28 +60,6 @@ public function debug($message = true, array $context = [])
             }
             $this->log(LogLevel::DEBUG, $message, $context);
         }
-
-        return $this;
-    }
-
-    /**
-     * Output log message.
-     *
-     * @param mixed        $level
-     * @param string       $message
-     * @param array<mixed> $context
-     *
-     * @return $this
-     */
-    public function log($level, $message, array $context = [])
-    {
-        if (TraitUtil::hasAppScopeTrait($this) && $this->issetApp() && $this->getApp()->logger instanceof \Psr\Log\LoggerInterface) {
-            $this->getApp()->logger->log($level, $message, $context);
-        } else {
-            $this->_echoStderr($message . "\n");
-        }
-
-        return $this;
     }
 
     /**
@@ -79,7 +71,7 @@ public function log($level, $message, array $context = [])
      * Place debugTraceChange inside your hook and give unique $trace identifier. If the method
      * is invoked through different call paths, this debug info will be logged.
      *
-     * Do not leave this method in production code !!!
+     * Do not use this method in production code !!!
      */
     public function debugTraceChange(string $trace = 'default'): void
     {
@@ -94,7 +86,7 @@ public function debugTraceChange(string $trace = 'default'): void
             $d1 = array_diff($this->_previousTrace[$trace], $bt);
             $d2 = array_diff($bt, $this->_previousTrace[$trace]);
 
-            $this->log('debug', 'Call path for ' . $trace . ' has diverged (was ' . implode(', ', $d1) . ', now ' . implode(', ', $d2) . ")\n");
+            $this->log(LogLevel::DEBUG, 'Call path for ' . $trace . ' has diverged (was ' . implode(', ', $d1) . ', now ' . implode(', ', $d2) . ")\n");
         }
 
         $this->_previousTrace[$trace] = $bt;
@@ -103,14 +95,12 @@ public function debugTraceChange(string $trace = 'default'): void
     /**
      * System is unusable.
      *
-     * @param string       $message
-     * @param array<mixed> $context
-     *
-     * @return $this
+     * @param string|\Stringable $message
+     * @param array<mixed>       $context
      */
-    public function emergency($message, array $context = [])
+    public function emergency($message, array $context = []): void
     {
-        return $this->log(LogLevel::EMERGENCY, $message, $context);
+        $this->log(LogLevel::EMERGENCY, $message, $context);
     }
 
     /**
@@ -119,43 +109,37 @@ public function emergency($message, array $context = [])
      * Example: Entire website down, database unavailable, etc. This should
      * trigger the SMS alerts and wake you up.
      *
-     * @param string       $message
-     * @param array<mixed> $context
-     *
-     * @return $this
+     * @param string|\Stringable $message
+     * @param array<mixed>       $context
      */
-    public function alert($message, array $context = [])
+    public function alert($message, array $context = []): void
     {
-        return $this->log(LogLevel::ALERT, $message, $context);
+        $this->log(LogLevel::ALERT, $message, $context);
     }
 
     /**
      * Critical conditions.
      *
      * Example: Application component unavailable, unexpected exception.
      *
-     * @param string       $message
-     * @param array<mixed> $context
-     *
-     * @return $this
+     * @param string|\Stringable $message
+     * @param array<mixed>       $context
      */
-    public function critical($message, array $context = [])
+    public function critical($message, array $context = []): void
     {
-        return $this->log(LogLevel::CRITICAL, $message, $context);
+        $this->log(LogLevel::CRITICAL, $message, $context);
     }
 
     /**
      * Runtime errors that do not require immediate action but should typically
      * be logged and monitored.
      *
-     * @param string       $message
-     * @param array<mixed> $context
-     *
-     * @return $this
+     * @param string|\Stringable $message
+     * @param array<mixed>       $context
      */
-    public function error($message, array $context = [])
+    public function error($message, array $context = []): void
     {
-        return $this->log(LogLevel::ERROR, $message, $context);
+        $this->log(LogLevel::ERROR, $message, $context);
     }
 
     /**
@@ -164,41 +148,35 @@ public function error($message, array $context = [])
      * Example: Use of deprecated APIs, poor use of an API, undesirable things
      * that are not necessarily wrong.
      *
-     * @param string       $message
-     * @param array<mixed> $context
-     *
-     * @return $this
+     * @param string|\Stringable $message
+     * @param array<mixed>       $context
      */
-    public function warning($message, array $context = [])
+    public function warning($message, array $context = []): void
     {
-        return $this->log(LogLevel::WARNING, $message, $context);
+        $this->log(LogLevel::WARNING, $message, $context);
     }
 
     /**
      * Normal but significant events.
      *
-     * @param string       $message
-     * @param array<mixed> $context
-     *
-     * @return $this
+     * @param string|\Stringable $message
+     * @param array<mixed>       $context
      */
-    public function notice($message, array $context = [])
+    public function notice($message, array $context = []): void
     {
-        return $this->log(LogLevel::NOTICE, $message, $context);
+        $this->log(LogLevel::NOTICE, $message, $context);
     }
 
     /**
      * Interesting events.
      *
      * Example: User logs in, SQL logs.
      *
-     * @param string       $message
-     * @param array<mixed> $context
-     *
-     * @return $this
+     * @param string|\Stringable $message
+     * @param array<mixed>       $context
      */
-    public function info($message, array $context = [])
+    public function info($message, array $context = []): void
     {
-        return $this->log(LogLevel::INFO, $message, $context);
+        $this->log(LogLevel::INFO, $message, $context);
     }
 }

tests/DebugTraitTest.php

@@ -16,7 +16,7 @@ public function testDebug(): void
 
         self::assertFalse($m->debug);
 
-        $m->debug();
+        $m->debug(true);
         self::assertTrue($m->debug);
 
         $m->debug(false);
@@ -28,56 +28,53 @@ public function testDebug(): void
 
     public function testDebugOutput(): void
     {
-        $this->expectOutputString("[Atk4\\Core\\Tests\\DebugMock]: debug test1\n");
-
         $m = new DebugMock();
-        $m->debug();
+        $m->debug(true);
 
+        $this->expectOutputString("[Atk4\\Core\\Tests\\DebugMock]: debug test1\n");
         $m->debug('debug test1');
     }
 
     public function testDebugNoOutput(): void
     {
-        $this->expectOutputString('');
-
         $m = new DebugMock();
 
+        $this->expectOutputString('');
         $m->debug('debug test2');
     }
 
     public function testDebugApp(): void
     {
-        $this->expectOutputString('');
-
         $app = new DebugAppMock();
         $app->logger = $app;
 
         $m = new DebugMock();
         $m->setApp($app);
-        $m->debug();
+        $m->debug(true);
 
+        $this->expectOutputString('');
         $m->debug('debug test2');
 
         self::assertSame(['debug', 'debug test2', []], $app->log);
     }
 
     public function testLog1(): void
     {
-        $this->expectOutputString("debug test3\n");
-
         $m = new DebugMock();
+
+        $this->expectOutputString("debug test3\n");
         $m->log('warning', 'debug test3');
     }
 
     public function testLog2(): void
     {
-        $this->expectOutputString('');
-
         $app = new DebugAppMock();
         $app->logger = $app;
 
         $m = new DebugMock();
         $m->setApp($app);
+
+        $this->expectOutputString('');
         $m->log('warning', 'debug test3');
 
         self::assertSame(['warning', 'debug test3', []], $app->log);
@@ -166,11 +163,7 @@ class DebugAppMock implements \Psr\Log\LoggerInterface
     /** @var self */
     public $logger;
 
-    /**
-     * @param mixed  $level
-     * @param string $message
-     */
-    public function log($level, $message, array $context = [])
+    public function log($level, $message, array $context = []): void
     {
         $this->log = [$level, $message, $context];
     }