refactor: documents

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
2026-03-03 22:13:36 -05:00
parent 85e89dca87
commit 1f3e87535b
45 changed files with 1667 additions and 676 deletions
--- a/core/lib/Logger/SystemdLogger.php
+++ b/core/lib/Logger/SystemdLogger.php
@@ -0,0 +1,112 @@
+<?php
+
+namespace KTXC\Logger;
+
+use Psr\Log\LoggerInterface;
+use Psr\Log\LogLevel;
+
+/**
+ * PSR-3 logger that writes to stderr using the journald/systemd SD_JOURNAL_PREFIX
+ * format: a syslog-priority number wrapped in angle brackets followed by the message.
+ *
+ * journald automatically parses the "<N>" prefix and maps it to the corresponding
+ * log priority, so log entries appear in the journal with the correct severity.
+ *
+ * Format: <priority>LEVEL [channel] interpolated-message {"context":"key",...}
+ */
+class SystemdLogger implements LoggerInterface
+{
+    /** Maps PSR-3 levels to RFC 5424 / syslog priority numbers */
+    private const PRIORITY = [
+        LogLevel::EMERGENCY => 0,
+        LogLevel::ALERT     => 1,
+        LogLevel::CRITICAL  => 2,
+        LogLevel::ERROR     => 3,
+        LogLevel::WARNING   => 4,
+        LogLevel::NOTICE    => 5,
+        LogLevel::INFO      => 6,
+        LogLevel::DEBUG     => 7,
+    ];
+
+    /** @var resource */
+    private $stderr;
+
+    public function __construct(private readonly string $channel = 'app')
+    {
+        $this->stderr = fopen('php://stderr', 'w');
+    }
+
+    public function __destruct()
+    {
+        if (is_resource($this->stderr)) {
+            fclose($this->stderr);
+        }
+    }
+
+    public function emergency($message, array $context = []): void { $this->log(LogLevel::EMERGENCY, $message, $context); }
+    public function alert($message, array $context = []): void      { $this->log(LogLevel::ALERT,     $message, $context); }
+    public function critical($message, array $context = []): void   { $this->log(LogLevel::CRITICAL,  $message, $context); }
+    public function error($message, array $context = []): void      { $this->log(LogLevel::ERROR,     $message, $context); }
+    public function warning($message, array $context = []): void    { $this->log(LogLevel::WARNING,   $message, $context); }
+    public function notice($message, array $context = []): void     { $this->log(LogLevel::NOTICE,    $message, $context); }
+    public function info($message, array $context = []): void       { $this->log(LogLevel::INFO,      $message, $context); }
+    public function debug($message, array $context = []): void      { $this->log(LogLevel::DEBUG,     $message, $context); }
+
+    public function log($level, $message, array $context = []): void
+    {
+        // Extract tenant id injected by TenantAwareLogger; default to 'system'.
+        $tenantId = isset($context['__tenant']) && is_string($context['__tenant'])
+            ? $context['__tenant']
+            : 'system';
+        unset($context['__tenant']);
+
+        $level    = strtolower((string) $level);
+        $priority = self::PRIORITY[$level] ?? 7;
+
+        $interpolated = $this->interpolate((string) $message, $context);
+        $contextStr   = empty($context) ? '' : ' ' . $this->encodeContext($context);
+
+        $line = sprintf(
+            "<%d>%s [%s] [%s] %s%s\n",
+            $priority,
+            strtoupper($level),
+            $this->channel,
+            $tenantId,
+            $interpolated,
+            $contextStr,
+        );
+
+        fwrite($this->stderr, $line);
+    }
+
+    private function interpolate(string $message, array $context): string
+    {
+        if (!str_contains($message, '{')) {
+            return $message;
+        }
+        $replace = [];
+        foreach ($context as $key => $val) {
+            if (!is_array($val) && !is_object($val)) {
+                $replace['{' . $key . '}'] = (string) $val;
+            }
+        }
+        return strtr($message, $replace);
+    }
+
+    private function encodeContext(array $context): string
+    {
+        $clean = [];
+        foreach ($context as $k => $v) {
+            if ($v instanceof \Throwable) {
+                $clean[$k] = ['type' => get_class($v), 'message' => $v->getMessage()];
+            } elseif (is_resource($v)) {
+                $clean[$k] = 'resource(' . get_resource_type($v) . ')';
+            } elseif (is_object($v)) {
+                $clean[$k] = method_exists($v, '__toString') ? (string) $v : ['object' => get_class($v)];
+            } else {
+                $clean[$k] = $v;
+            }
+        }
+        return json_encode($clean, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE) ?: '{}';
+    }
+}