Add model query builder

README.md

@@ -269,6 +269,60 @@ class UserService
 
 Available helpers are `query($sql, $parameters)`, `execute($sql, $parameters)`, `pdo()`, and `transaction($callback)`. Query results expose `all()`, `first()`, `value()`, `affectedRows()`, and the raw `PDOStatement`.
 
+### Query Builder and Models
+
+Use the table query builder for simple fluent queries:
+
+```php
+$users = $db->table('users')
+    ->select('id', 'email')
+    ->where('active', true)
+    ->orderBy('id', 'desc')
+    ->limit(10)
+    ->get();
+```
+
+Models extend `Shift\Database\Model`. Public properties represent database columns:
+
+```php
+use Shift\Database\Attributes\Cast;
+use Shift\Database\Attributes\Guarded;
+use Shift\Database\Attributes\PrimaryKey;
+use Shift\Database\Model;
+
+class User extends Model
+{
+    protected string $table = 'users';
+
+    #[PrimaryKey]
+    #[Cast('int')]
+    public ?int $id = null;
+
+    public string $email = '';
+
+    #[Guarded]
+    public string $role = 'user';
+
+    #[Cast('array')]
+    public array $meta = [];
+
+    #[Cast('datetime')]
+    public ?DateTimeImmutable $created_at = null;
+}
+```
+
+Model queries return hydrated model instances:
+
+```php
+$user = User::query($db)->where('email', 'dev@example.com')->first();
+$user = User::find(1, $db);
+$user = User::create(['email' => 'dev@example.com'], $db);
+$user->role = 'admin';
+$user->save($db);
+```
+
+`#[Guarded]` fields are ignored during mass assignment through `create()` and query `update()`, but can be set explicitly on a model instance before `save()`. Supported casts include `int`, `float`, `bool`, `string`, `array`, `date`, `datetime`, and class names. Class casts use `fromArray()` when available.
+
 ## Service Container
 
 The container can resolve registered services and build classes with typed constructor dependencies:

REFACTORING.md

@@ -29,6 +29,7 @@ ShiftPHP is moving toward an API-only modular monolith. View templates, compiled
 - [x] CLI create generators for modules and module-owned classes with file-based stubs.
 - [x] `.env` loading for application configuration.
 - [x] Native PDO database configuration, lazy connection, and basic query API.
+- [x] Fluent query builder and attribute-driven database models.
 - [x] Removal of view storage and example page assets from runtime.
 - [x] Removal of legacy `application/controllers` and `application/routes.php`.
 - [x] Domain-oriented framework namespaces:

docs/index.html

@@ -423,6 +423,50 @@ <h2>Environment and Database</h2>
 }</code></pre>
 
             <p>Use <code>query()</code> for prepared queries, <code>execute()</code> for write statements, <code>pdo()</code> for raw PDO access, and <code>transaction()</code> for transactional work.</p>
+
+            <h3>Query Builder</h3>
+            <pre><code>$users = $db-&gt;table('users')
+    -&gt;select('id', 'email')
+    -&gt;where('active', true)
+    -&gt;orderBy('id', 'desc')
+    -&gt;limit(10)
+    -&gt;get();</code></pre>
+
+            <h3>Models</h3>
+            <p>Models extend <code>Shift\Database\Model</code>. Public properties are database columns, and model attributes describe primary keys, guarded fields, and casts.</p>
+
+            <pre><code>use Shift\Database\Attributes\Cast;
+use Shift\Database\Attributes\Guarded;
+use Shift\Database\Attributes\PrimaryKey;
+use Shift\Database\Model;
+
+class User extends Model
+{
+    protected string $table = 'users';
+
+    #[PrimaryKey]
+    #[Cast('int')]
+    public ?int $id = null;
+
+    public string $email = '';
+
+    #[Guarded]
+    public string $role = 'user';
+
+    #[Cast('array')]
+    public array $meta = [];
+
+    #[Cast('datetime')]
+    public ?DateTimeImmutable $created_at = null;
+}</code></pre>
+
+            <pre><code>$user = User::query($db)-&gt;where('email', 'dev@example.com')-&gt;first();
+$user = User::find(1, $db);
+$user = User::create(['email' =&gt; 'dev@example.com'], $db);
+$user-&gt;role = 'admin';
+$user-&gt;save($db);</code></pre>
+
+            <p><code>#[Guarded]</code> fields are ignored during mass assignment through <code>create()</code> and query <code>update()</code>, but can be set explicitly before <code>save()</code>. Supported casts include <code>int</code>, <code>float</code>, <code>bool</code>, <code>string</code>, <code>array</code>, <code>date</code>, <code>datetime</code>, and class names. Class casts use <code>fromArray()</code> when available.</p>
         </section>
 
         <section id="cli">

src/Console/Commands/CreateModel.php

@@ -25,6 +25,7 @@ public function execute(mixed ...$args): void
         $this->writeAndReport($path, $this->renderStub('model', [
             'module' => $module,
             'class' => $class,
+            'table' => NameFormatter::tableName($class),
         ]));
     }
 

src/Console/Generator/NameFormatter.php

@@ -30,6 +30,13 @@ public static function commandName(string $className): string
         return implode(':', $parts);
     }
 
+    public static function tableName(string $className): string
+    {
+        $snake = strtolower((string) preg_replace('/(?<!^)[A-Z]/', '_$0', $className));
+
+        return str_ends_with($snake, 's') ? $snake : $snake . 's';
+    }
+
     public static function slug(string $name): string
     {
         $parts = preg_split('/[^a-zA-Z0-9]+/', $name, -1, PREG_SPLIT_NO_EMPTY) ?: [];

src/Console/Generator/stubs/model.stub

@@ -2,6 +2,9 @@
 
 namespace Modules\{{ module }}\Models;
 
-class {{ class }}
+use Shift\Database\Model;
+
+class {{ class }} extends Model
 {
+    protected string $table = '{{ table }}';
 }

src/Database/Attributes/Cast.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Shift\Database\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class Cast
+{
+    public function __construct(
+        public readonly string $type,
+        public readonly ?string $format = null
+    ) {
+    }
+}

src/Database/Attributes/Guarded.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Shift\Database\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class Guarded
+{
+}

src/Database/Attributes/PrimaryKey.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Shift\Database\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class PrimaryKey
+{
+}

src/Database/Database.php

@@ -50,6 +50,11 @@ public function query(string $sql, array $parameters = []): QueryResult
         }
     }
 
+    public function table(string $table): QueryBuilder
+    {
+        return new QueryBuilder($this, $table);
+    }
+
     public function execute(string $sql, array $parameters = []): int
     {
         return $this->query($sql, $parameters)->affectedRows();
@@ -71,6 +76,11 @@ public function transaction(callable $callback): mixed
         }
     }
 
+    public function lastInsertId(?string $name = null): string
+    {
+        return $this->pdo()->lastInsertId($name);
+    }
+
     private function options(): array
     {
         return $this->config->options + [