feat: add PSR-3 Trap logger with STDERR fallback (#212)

Co-authored-by: roxblnfk <roxblnfk@ya.ru>

Author: petrdobr

composer.json

@@ -46,6 +46,7 @@
         "php-http/message": "^1.15",
         "psr/container": "^1.1 || ^2.0",
         "psr/http-message": "^1.1 || ^2",
+        "psr/log": "^2 || ^3",
         "symfony/console": "^6.4 || ^7 || ^8",
         "symfony/var-dumper": "^6.3 || ^7 || ^8",
         "yiisoft/injector": "^1.2"

composer.lock

@@ -8,6 +8,8 @@
 use Buggregator\Trap\Client\TrapHandle\Counter;
 use Buggregator\Trap\Client\TrapHandle\Dumper as VarDumper;
 use Buggregator\Trap\Client\TrapHandle\StaticState;
+use Buggregator\Trap\Log\TrapLogger;
+use Psr\Log\LoggerInterface;
 use Symfony\Component\VarDumper\Caster\TraceStub;
 
 /**
@@ -21,6 +23,9 @@ final class TrapHandle
     private int $depth = 0;
     private readonly StaticState $staticState;
 
+    /** @var array<string, TrapLogger> */
+    private static array $loggers = [];
+
     private function __construct(
         private array $values,
     ) {
@@ -35,6 +40,40 @@ public static function fromArray(array $array): self
         return new self($array);
     }
 
+    /**
+     * Get a PSR-3 compatible logger instance for Trap client logging.
+     *
+     * Uses TRAP_MONOLOG_HOST and TRAP_MONOLOG_PORT env variables,
+     * falling back to 127.0.0.1:9913.
+     *
+     * @param non-empty-string $channel Monolog channel name the records will be tagged with.
+     */
+    public static function logger(string $channel = 'trap'): LoggerInterface
+    {
+        return self::$loggers[$channel] ??= self::createLogger($channel);
+    }
+
+    /**
+     * @param non-empty-string $channel
+     */
+    private static function createLogger(string $channel): TrapLogger
+    {
+        $host = self::getEnvValue('TRAP_MONOLOG_HOST', '127.0.0.1');
+        $port = self::getEnvValue('TRAP_MONOLOG_PORT', '9913');
+
+        $port = \is_numeric($port) ? (int) $port : 9913;
+
+        if ($port < 1 || $port > 65535) {
+            $port = 9913;
+        }
+
+        return new TrapLogger(
+            host: $host,
+            port: $port,
+            channel: $channel,
+        );
+    }
+
     /**
      * Create a new instance with a single value.
      *
@@ -214,6 +253,25 @@ public function __destruct()
         $this->haveToSend() and $this->sendDump();
     }
 
+    private static function getEnvValue(string $name, string $default): string
+    {
+        if (\array_key_exists($name, $_ENV)) {
+            return $_ENV[$name];
+        }
+
+        $value = \getenv($name, true);
+        if ($value !== false) {
+            return $value;
+        }
+
+        $value = \getenv($name);
+        if ($value !== false) {
+            return $value;
+        }
+
+        return $default;
+    }
+
     private function sendDump(): void
     {
         $staticState = StaticState::getValue();
@@ -223,9 +281,9 @@ private function sendDump(): void
         try {
             // Set default values if not set
             if (!isset($_SERVER['VAR_DUMPER_FORMAT'], $_SERVER['VAR_DUMPER_SERVER'])) {
-                $_SERVER['VAR_DUMPER_FORMAT'] = $this->getEnvValue('VAR_DUMPER_FORMAT', 'server');
+                $_SERVER['VAR_DUMPER_FORMAT'] = self::getEnvValue('VAR_DUMPER_FORMAT', 'server');
                 // todo use the config file in the future
-                $_SERVER['VAR_DUMPER_SERVER'] = $this->getEnvValue('VAR_DUMPER_SERVER', '127.0.0.1:9912');
+                $_SERVER['VAR_DUMPER_SERVER'] = self::getEnvValue('VAR_DUMPER_SERVER', '127.0.0.1:9912');
             }
 
             // Dump single value
@@ -248,25 +306,6 @@ private function sendDump(): void
         }
     }
 
-    private function getEnvValue(string $name, string $default): string
-    {
-        if (\array_key_exists($name, $_ENV)) {
-            return $_ENV[$name];
-        }
-
-        $value = \getenv($name, true);
-        if ($value !== false) {
-            return $value;
-        }
-
-        $value = \getenv($name);
-        if ($value !== false) {
-            return $value;
-        }
-
-        return $default;
-    }
-
     private function haveToSend(): bool
     {
         if (!$this->haveToSend || $this->values === []) {