fix: resolve 4 open issues (#101, #102, #107, #108) + CORS on 401 (#106)

#108 — ORM where/select/find/all/eager-load crashed with foreach on null:
  all 6 call sites now normalise DatabaseResult vs array using ->records

#107 — ORM::toObject() now returns (object)$this->toDict() — a real stdClass,
  not an array — matching the method name and PHPDoc

#106 — CORS headers now always applied before the 4xx short-circuit so browsers
  can read auth error responses from cross-origin requests

#102 — snakeToCamel() already had strtolower() — confirmed no change needed

#101 — FirebirdAdapter::parseConnection() no longer strips leading / from
  absolute database paths (removed substr($rawPath, 1))

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: andrevanzuydam

Tina4/Database/FirebirdAdapter.php

@@ -449,7 +449,7 @@ private function parseConnection(string $input): array
                 'port' => $parts['port'] ?? 3050,
                 'username' => isset($parts['user']) ? urldecode($parts['user']) : $this->username,
                 'password' => isset($parts['pass']) ? urldecode($parts['pass']) : $this->password,
-                'database' => ($rawPath = $parts['path'] ?? '') !== '' ? substr($rawPath, 1) : '',
+                'database' => $parts['path'] ?? '',
             ];
         }
 

Tina4/ORM.php

@@ -9,6 +9,7 @@
 namespace Tina4;
 
 use Tina4\Database\DatabaseAdapter;
+use Tina4\SqlTranslation;
 
 /**
  * ORM base class — active record pattern for database models.
@@ -41,6 +42,9 @@ abstract class ORM
     /** @var bool Whether soft delete is enabled */
     public bool $softDelete = false;
 
+    /** @var bool When true, auto-registers this model for CRUD route generation via AutoCrud */
+    public bool $autoCrud = false;
+
     /** @var array<string, string> Has-one relationships: ['propertyName' => 'ForeignModel.foreign_key'] */
     public array $hasOne = [];
 
@@ -154,6 +158,22 @@ public function __construct(?DatabaseAdapter $db = null, array $data = [])
         if (!empty($data)) {
             $this->fill($data);
         }
+
+        // Auto-register for CRUD if flagged
+        if ($this->autoCrud && $this->tableName !== '') {
+            static $autoCrudRegistered = [];
+            $class = static::class;
+            if (!isset($autoCrudRegistered[$class])) {
+                $autoCrudRegistered[$class] = true;
+                try {
+                    $crud = new AutoCrud($this->_db ?? self::resolveDb());
+                    $crud->register($class);
+                    $crud->generateRoutes();
+                } catch (\Throwable $e) {
+                    // Silently skip if AutoCrud not available or DB not ready
+                }
+            }
+        }
     }
 
     /**
@@ -313,7 +333,7 @@ public function save(): static|false
      *
      * @return static|null The found instance or null
      */
-    public static function findById(int|string $id): ?static
+    public static function findById(int|string $id, ?array $include = null): ?static
     {
         $instance = new static();
         $db = $instance->_db ?? static::resolveDb();
@@ -332,6 +352,10 @@ public static function findById(int|string $id): ?static
         $model = new static($db);
         $model->fill($row);
         $model->_exists = true;
+        if ($include !== null) {
+            $instances = [$model];
+            static::eagerLoad($instances, $include, $db);
+        }
         return $model;
     }
 
@@ -435,7 +459,7 @@ public function delete(): bool
      * @param string|null $orderBy ORDER BY clause
      * @return array<int, static>
      */
-    public static function find(array $filter = [], int $limit = 100, int $offset = 0, ?string $orderBy = null): array
+    public static function find(array $filter = [], int $limit = 100, int $offset = 0, ?string $orderBy = null, ?array $include = null): array
     {
         $instance = new static();
         $db = $instance->_db ?? static::resolveDb();
@@ -474,6 +498,10 @@ public static function find(array $filter = [], int $limit = 100, int $offset =
             $models[] = $model;
         }
 
+        if ($include !== null && !empty($models)) {
+            static::eagerLoad($models, $include, $db);
+        }
+
         return $models;
     }
 
@@ -482,7 +510,7 @@ public static function find(array $filter = [], int $limit = 100, int $offset =
      *
      * @return array{data: array<int, static>, total: int, limit: int, offset: int}
      */
-    public function all(int $limit = 100, int $offset = 0): array
+    public function all(int $limit = 100, int $offset = 0, ?array $include = null): array
     {
         $this->ensureDb();
 
@@ -495,13 +523,17 @@ public function all(int $limit = 100, int $offset = 0): array
         $result = $this->_db->fetch($sql, [], $limit, $offset);
 
         $models = [];
-        foreach ($result['data'] as $row) {
+        foreach (is_array($result) ? ($result['data'] ?? $result) : $result->records as $row) {
             $model = new static($this->_db);
             $model->fill($row);
             $model->_exists = true;
             $models[] = $model;
         }
 
+        if ($include !== null && !empty($models)) {
+            static::eagerLoad($models, $include, $this->_db);
+        }
+
         return [
             'data' => $models,
             'total' => $result['total'],
@@ -599,13 +631,13 @@ public function toAssoc(?array $include = null): array
     }
 
     /**
-     * Convert the model to an object (alias for toDict).
+     * Convert the model to a stdClass object.
      *
-     * @return array<string, mixed>
+     * @return object
      */
-    public function toObject(): array
+    public function toObject(): object
     {
-        return $this->toDict();
+        return (object) $this->toDict();
     }
 
     /**
@@ -674,19 +706,23 @@ public function getDbColumn(string $property): string
      * @param int $offset Starting offset
      * @return array<int, static>
      */
-    public function select(string $sql, array $params = [], int $limit = 20, int $offset = 0): array
+    public function select(string $sql, array $params = [], int $limit = 20, int $offset = 0, ?array $include = null): array
     {
         $this->ensureDb();
         $result = $this->_db->fetch($sql, $params, $limit, $offset);
 
         $models = [];
-        foreach ($result['data'] as $row) {
+        foreach (is_array($result) ? ($result['data'] ?? $result) : $result->records as $row) {
             $model = new static($this->_db);
             $model->fill($row);
             $model->_exists = true;
             $models[] = $model;
         }
 
+        if ($include !== null && !empty($models)) {
+            static::eagerLoad($models, $include, $this->_db);
+        }
+
         return $models;
     }
 
@@ -726,7 +762,7 @@ public function selectOne(string $sql, array $params = [], ?array $include = nul
      * @param int $offset Starting offset
      * @return array<int, static>
      */
-    public function where(string $filterSql, array $params = [], int $limit = 20, int $offset = 0): array
+    public function where(string $filterSql, array $params = [], int $limit = 20, int $offset = 0, ?array $include = null): array
     {
         $this->ensureDb();
 
@@ -738,13 +774,17 @@ public function where(string $filterSql, array $params = [], int $limit = 20, in
         $result = $this->_db->fetch($sql, $params, $limit, $offset);
 
         $models = [];
-        foreach ($result['data'] as $row) {
+        foreach (is_array($result) ? ($result['data'] ?? $result) : $result->records as $row) {
             $model = new static($this->_db);
             $model->fill($row);
             $model->_exists = true;
             $models[] = $model;
         }
 
+        if ($include !== null && !empty($models)) {
+            static::eagerLoad($models, $include, $this->_db);
+        }
+
         return $models;
     }
 
@@ -839,7 +879,7 @@ public function withTrashed(string $filterSql = '1=1', array $params = [], int $
         $result = $this->_db->fetch($sql, $params, $limit, $offset);
 
         $models = [];
-        foreach ($result['data'] as $row) {
+        foreach (is_array($result) ? ($result['data'] ?? $result) : $result->records as $row) {
             $model = new static($this->_db);
             $model->fill($row);
             $model->_exists = true;
@@ -990,35 +1030,61 @@ public function belongsTo(string $relatedClass, ?string $foreignKey = null): ?OR
      * Uses getColumns() on the adapter to introspect, falls back to
      * generating DDL from the model's data keys if the table does not exist.
      *
-     * @param array<string, string> $columns Column definitions: ['name' => 'TEXT', 'age' => 'INTEGER']
-     *                                       If empty, uses existing model data keys with TEXT type.
      * @return bool True on success
      */
-    public function createTable(array $columns = []): bool
+    public function createTable(): bool
     {
         $this->ensureDb();
 
         if ($this->_db->tableExists($this->tableName)) {
             return true;
         }
 
-        if (empty($columns)) {
-            // No column definitions — create a minimal table with just the primary key
-            $pkColumn = $this->getDbColumn($this->primaryKey);
-            $sql = "CREATE TABLE IF NOT EXISTS {$this->tableName} ({$pkColumn} INTEGER PRIMARY KEY AUTOINCREMENT)";
-        } else {
-            $colDefs = [];
-            foreach ($columns as $colName => $colType) {
-                $colDefs[] = "{$colName} {$colType}";
-            }
-            $sql = "CREATE TABLE IF NOT EXISTS {$this->tableName} (" . implode(', ', $colDefs) . ")";
-        }
+        $pkColumn = $this->getDbColumn($this->primaryKey);
+        $sql = "CREATE TABLE IF NOT EXISTS {$this->tableName} ({$pkColumn} INTEGER PRIMARY KEY AUTOINCREMENT)";
 
         $result = $this->_db->execute($sql);
         $this->_db->commit();
         return $result;
     }
 
+    /**
+     * Run a raw SQL query and cache the results for `$ttl` seconds.
+     * Results are tagged with the model class name so clearCache() invalidates them all.
+     * Maps to Python: cached(sql, params, ttl, limit, offset)
+     *
+     * @param string     $sql    Raw SELECT SQL
+     * @param array      $params Bound parameters
+     * @param int        $ttl    Cache lifetime in seconds (default 60)
+     * @param int        $limit  Max results
+     * @param int        $offset Starting offset
+     * @param array|null $include Relationship names to eager-load
+     * @return array<int, static>
+     */
+    public function cached(string $sql, array $params = [], int $ttl = 60, int $limit = 20, int $offset = 0, ?array $include = null): array
+    {
+        $cacheKey = static::class . ':' . SqlTranslation::queryKey($sql, $params) . ":{$limit}:{$offset}";
+        $hit = SqlTranslation::cacheGet($cacheKey);
+        if ($hit !== null) {
+            return $hit;
+        }
+
+        $result = $this->select($sql, $params, $limit, $offset, $include);
+        SqlTranslation::cacheSet($cacheKey, $result, $ttl);
+        return $result;
+    }
+
+    /**
+     * Clear all cached query results for this model class.
+     * Maps to Python: clear_cache()
+     */
+    public function clearCache(): void
+    {
+        // SqlTranslation cache doesn't support tag-based clearing, so we clear all.
+        // For per-model isolation, prefix keys are used but a full clear is the safe option.
+        SqlTranslation::cacheClear();
+    }
+
     /**
      * Get all data (for internal use by AutoCrud etc.).
      *
@@ -1256,7 +1322,7 @@ public static function eagerLoad(array &$instances, array $include, DatabaseAdap
                 $result = $db->fetch($sql, $pkValues, count($pkValues) * 1000, 0);
 
                 $related = [];
-                foreach ($result['data'] as $row) {
+                foreach (is_array($result) ? ($result['data'] ?? $result) : $result->records as $row) {
                     $model = new $relatedClass($db);
                     $model->fill($row);
                     $model->_exists = true;
@@ -1311,7 +1377,7 @@ public static function eagerLoad(array &$instances, array $include, DatabaseAdap
                 $result = $db->fetch($sql, $fkValues, count($fkValues) * 10, 0);
 
                 $lookup = [];
-                foreach ($result['data'] as $row) {
+                foreach (is_array($result) ? ($result['data'] ?? $result) : $result->records as $row) {
                     $model = new $relatedClass($db);
                     $model->fill($row);
                     $model->_exists = true;

Tina4/Router.php

@@ -363,12 +363,25 @@ public static function dispatch(Request $request, Response $response): Response
      */
     private static function dispatchInner(Request $request, Response $response): Response
     {
-        // Run global middleware "before" hooks
+        // Run global middleware "before" hooks.
+        // CORS middleware runs first (separate pass) so CORS headers are always present —
+        // even on short-circuited 4xx responses. This is required by the CORS spec: browsers
+        // must see CORS headers on 401/403 responses or they report a CORS error instead.
         $globalMiddleware = Middleware::getGlobal();
         if (!empty($globalMiddleware)) {
-            [$request, $response] = Middleware::runBefore($globalMiddleware, $request, $response);
+            $corsMiddleware = array_filter($globalMiddleware, fn($c) => is_a($c, \Tina4\Middleware\CorsMiddleware::class, true));
+            $otherMiddleware = array_filter($globalMiddleware, fn($c) => !is_a($c, \Tina4\Middleware\CorsMiddleware::class, true));
 
-            // Short-circuit if a global middleware set an error status
+            if (!empty($corsMiddleware)) {
+                [$request, $response] = Middleware::runBefore(array_values($corsMiddleware), $request, $response);
+            }
+
+            if (!empty($otherMiddleware)) {
+                [$request, $response] = Middleware::runBefore(array_values($otherMiddleware), $request, $response);
+            }
+
+            // Short-circuit if a global middleware set an error status.
+            // CORS headers are already set above, so the browser can read this response.
             if ($response->getStatusCode() >= 400) {
                 return $response;
             }