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/LoggerFactory.php
+++ b/core/lib/Logger/LoggerFactory.php
@@ -0,0 +1,87 @@
+<?php
+
+namespace KTXC\Logger;
+
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
+
+/**
+ * Creates a PSR-3 LoggerInterface instance from the application config.
+ *
+ * Reads the 'log' key from the system config array and builds:
+ *   1. A driver-specific inner logger (file, systemd, syslog, null).
+ *   2. A LevelFilterLogger decorator that discards messages below the
+ *      configured minimum level.
+ *
+ * Per-tenant routing (TenantAwareLogger) is applied separately inside the
+ * DI container definition in Kernel::configureContainer(), because that
+ * requires access to the SessionTenant singleton which lives in the container.
+ *
+ * Supported config keys inside $config['log']:
+ *
+ *   driver      string  'file' | 'systemd' | 'syslog' | 'null'   default: 'file'
+ *   level       string  PSR-3 level string (minimum to log)        default: 'debug'
+ *   per_tenant  bool    Route to per-tenant files (DI-level only)  default: false
+ *
+ *   -- file driver --
+ *   path        ?string Absolute log directory, null = {root}/var/log
+ *   channel     string  File basename without extension             default: 'app'
+ *
+ *   -- systemd driver --
+ *   channel     string  Channel tag embedded in each line          default: 'app'
+ *
+ *   -- syslog driver --
+ *   ident       string  openlog() identity tag                     default: 'ktrix'
+ *   facility    int     openlog() facility constant                 default: LOG_USER
+ *   channel     string  Prefix embedded in each syslog message     default: 'app'
+ */
+class LoggerFactory
+{
+    /**
+     * Build and return a configured, level-filtered PSR-3 logger.
+     *
+     * @param array  $config     The full system config array (reads $config['log']).
+     * @param string $projectDir Absolute project root path (used for default file path).
+     */
+    public static function create(array $config, string $projectDir): LoggerInterface
+    {
+        $logConfig = $config['log'] ?? [];
+
+        $driver  = $logConfig['driver']  ?? 'file';
+        $level   = $logConfig['level']   ?? 'debug';
+        $channel = $logConfig['channel'] ?? 'app';
+
+        // Validate level early for a clear error message.
+        LogLevelSeverity::validate($level);
+
+        $inner = match ($driver) {
+            'file'    => self::buildFileLogger($logConfig, $projectDir, $channel),
+            'systemd' => new SystemdLogger($channel),
+            'syslog'  => new SyslogLogger(
+                            $logConfig['ident']    ?? 'ktrix',
+                            $logConfig['facility'] ?? LOG_USER,
+                            $channel,
+                         ),
+            'null'    => new NullLogger(),
+            default   => throw new \RuntimeException(
+                            sprintf(
+                                'Unknown log driver "%s". Supported drivers: file, systemd, syslog, null.',
+                                $driver
+                            )
+                         ),
+        };
+
+        return new LevelFilterLogger($inner, $level);
+    }
+
+    private static function buildFileLogger(array $logConfig, string $projectDir, string $channel): FileLogger
+    {
+        $path = $logConfig['path'] ?? null;
+
+        if ($path === null || $path === '') {
+            $path = $projectDir . '/var/log';
+        }
+
+        return new FileLogger($path, $channel);
+    }
+}