documentation and env changes

config/packages/doctrine.php

@@ -1,5 +1,26 @@
 <?php
 
+/**
+ * Dynamic Doctrine DBAL configuration.
+ *
+ * This file complements `config/packages/doctrine.yaml`, not replacing it!:
+ * - YAML handles ORM mappings, naming strategy, caches, and env-specific tweaks.
+ * - This PHP config focuses on DBAL and runtime driver selection.
+ *
+ * Behavior:
+ * - Chooses the database driver from `DATABASE_DRIVER` (`postgres` or `sqlite`).
+ * - For Postgres:
+ *   - Uses `DATABASE_URL` (e.g. `postgresql://user:pass@host:5432/dbname`).
+ *   - Pins `serverVersion` (currently `16`) to avoid auto-detection issues.
+ * - For SQLite:
+ *   - Uses `DATABASE_SQLITE_PATH` when provided.
+ *   - Otherwise, defaults to `<projectDir>/var/data/database.sqlite`, creating the
+ *     directory and file if they do not already exist. (Recommended)
+ *
+ * This split keeps the mapping/caching config in YAML while allowing
+ * DBAL to adapt between Docker/postgres and local sqlite setups.
+ */
+
 declare(strict_types=1);
 
 use Symfony\Component\Filesystem\Filesystem;
@@ -7,6 +28,7 @@ use Symfony\Config\DoctrineConfig;
 use function Symfony\Component\DependencyInjection\Loader\Configurator\param;
 
 return static function (DoctrineConfig $doctrine): void {
+    // Normalize DATABASE_DRIVER and validate allowed values up front.
     $driver = strtolower((string) ($_ENV['DATABASE_DRIVER'] ?? $_SERVER['DATABASE_DRIVER'] ?? 'postgres'));
     $supportedDrivers = ['postgres', 'sqlite'];
 
@@ -18,6 +40,7 @@ return static function (DoctrineConfig $doctrine): void {
         ));
     }
 
+    // Configure the default DBAL connection.
     $dbal = $doctrine->dbal();
     $dbal->defaultConnection('default');
 
@@ -26,12 +49,14 @@ return static function (DoctrineConfig $doctrine): void {
     $connection->useSavepoints(true);
 
     if ('sqlite' === $driver) {
+        // SQLite: use a file-backed database by default.
         $connection->driver('pdo_sqlite');
 
         $hasCustomPath = array_key_exists('DATABASE_SQLITE_PATH', $_ENV)
             || array_key_exists('DATABASE_SQLITE_PATH', $_SERVER);
 
         if ($hasCustomPath) {
+            // Allow explicit database path via env overrides.
             $connection->path('%env(resolve:DATABASE_SQLITE_PATH)%');
         } else {
             $projectDir = dirname(__DIR__, 2);
@@ -50,7 +75,9 @@ return static function (DoctrineConfig $doctrine): void {
             $connection->path('%kernel.project_dir%/var/data/database.sqlite');
         }
     } else {
+        // Postgres (or other server-based driver) via DATABASE_URL.
         $connection->url('%env(resolve:DATABASE_URL)%');
+        // Keep the server version explicit so Doctrine does not need network calls to detect it.
         $connection->serverVersion('16');
         $connection->charset('utf8');
     }