Files
camelia-orm/docs/GUIA-PROGRAMADOR.md
T
dgarcia 66e93e3070 feat: initial commit of camelia/orm
Attribute-mapped Active Record ORM for MariaDB/MySQL over PDO.

- Attribute-driven metadata: TableName, PrimaryKey, AutoIncrement, Column,
  Guarded, Ignore, Required, Enum, Nullable, Length, Precision, Unique,
  UniqueGroup, Index, MaxLength.
- Relationship mapping: BelongsTo, HasOne, HasMany, BelongsToMany with
  batched eager loading and a 3-level depth limit.
- Orm entry point with fromArray, fromPdo, fromEnv and nested transactions.
- Immutable Query with Cond operators and GroupCond grouping.
- Repository read and write API, pagination, and typed exception hierarchy.
- Declares PHP >=8.3; Mago and PHPStan pin the parser to 8.3.
- MIT license.
2026-11-15 10:14:22 -03:00

1100 lines
34 KiB
Markdown

# camelia/orm — Guía del programador
Documentación de uso de la librería `camelia/orm`. Para el contrato de diseño completo, ver
[`especificaciones-orm.md`](especificaciones-orm.md). Para el arranque rápido, el
[`README`](README.md).
Esta guía está organizada **por tarea**: qué quieres hacer, no qué clases existen. La referencia de
API completa está al final.
---
## Índice
1. [Instalación y arranque](#1-instalación-y-arranque)
2. [Definir un modelo](#2-definir-un-modelo)
3. [Tipos y conversiones](#3-tipos-y-conversiones)
4. [Lectura: buscar filas](#4-lectura-buscar-filas)
5. [Condiciones de filtro](#5-condiciones-de-filtro)
6. [Escritura: guardar filas](#6-escritura-guardar-filas)
7. [Validación](#7-validación)
8. [Relaciones](#8-relaciones)
9. [Paginación](#9-paginación)
10. [Transacciones](#10-transacciones)
11. [Serialización a JSON](#11-serialización-a-json)
12. [Manejo de errores](#12-manejo-de-errores)
13. [Extensiones: auditoría, logs, reloj](#13-extensiones-auditoría-logs-reloj)
14. [Testing de código que usa el ORM](#14-testing-de-código-que-usa-el-orm)
15. [Recetas frecuentes](#15-recetas-frecuentes)
16. [Trampas y errores comunes](#16-trampas-y-errores-comunes)
17. [Referencia de API](#17-referencia-de-api)
---
## 1. Instalación y arranque
```bash
composer require camelia/orm
```
Crea el objeto raíz una vez por proceso y pásalo donde lo necesites. Es inmutable y seguro de
compartir.
```php
use Camelia\Orm\Orm;
$orm = Orm::fromArray([
'host' => '127.0.0.1',
'port' => 3306,
'user' => 'app',
'password' => 'secret',
'database' => 'erp',
]);
```
### Desde variables de entorno
```php
$orm = Orm::fromEnv();
```
Lee `CAMELIA_DB_HOST`, `CAMELIA_DB_USER`, `CAMELIA_DB_NAME` y `CAMELIA_DB_PASS` (todas
obligatorias) y opcionalmente `CAMELIA_DB_PORT` (3306) y `CAMELIA_DB_CHARSET` (utf8mb4). Si falta
alguna obligatoria, el mensaje de error lista **todas** las que faltan, no solo la primera.
### Desde un `PDO` existente
```php
$orm = Orm::fromPdo($pdo);
```
El `PDO` debe estar en `ERRMODE_EXCEPTION`. Si no, se lanza `ConfigurationException`: los modos
silenciosos son incompatibles con el contrato de errores de la librería.
### Claves de `fromArray`
| Clave | Obligatoria | Por defecto |
|---|---|---|
| `host` | sí | — |
| `user` | sí | — |
| `database` | sí | — |
| `password` | no | `''` |
| `port` | no | `3306` |
| `charset` | no | `utf8mb4` |
| `sslCa` | no | — (ruta al certificado CA) |
Las claves de extensión (`logger`, `auditListener`, `clock`, `slowQueryMs`) se explican en
[§13](#13-extensiones-auditoría-logs-reloj).
> **No hay singleton.** No existe `getInstance()` ni `reset()`. Si necesitas otra conexión, crea
> otro `Orm`.
---
## 2. Definir un modelo
Un modelo es una clase que extiende `Camelia\Orm\Model` con propiedades públicas tipadas.
```php
<?php
declare(strict_types=1);
namespace App\Models;
use Camelia\Orm\Attribute\{TableName, PrimaryKey, AutoIncrement, Guarded};
use Camelia\Orm\Model;
#[TableName('usuarios')]
final class Usuario extends Model
{
#[PrimaryKey, AutoIncrement]
public ?int $codigo = null;
public string $nombre = '';
public string $correo = '';
#[Guarded]
public string $passwordHash = '';
public bool $activo = true;
}
```
### Reglas obligatorias
Todas se validan en la **primera lectura** del modelo. Si algo está mal, lanza `MetadataException`
con la regla incumplida en el mensaje. No hay fallbacks ni valores por defecto ocultos.
| Regla | Qué exige |
|---|---|
| **M1** | La clase extiende `Model` |
| **M2** | `#[TableName('...')]` presente y no vacío |
| **M3** | Exactamente **una** propiedad con `#[PrimaryKey]` |
| **M4** | Las propiedades mapeadas son `public` y tienen tipo declarado |
| **M5** | Una relación es nulable (`?ModelX`) o `array` (uno a muchos) |
| **M6** | La propiedad FK tiene el mismo tipo que la PK referida |
| **M7** | No hay dos propiedades apuntando a la misma columna |
### Nombre de columna
Por defecto, `camelToSnake` de la propiedad:
| Propiedad | Columna |
|---|---|
| `nombre` | `nombre` |
| `codigoEmpresa` | `codigo_empresa` |
| `idZona` | `id_zona` |
Para un nombre distinto, usa `#[Column]`:
```php
#[Column('importe_total')]
public float $total = 0.0;
```
### Valores iniciales
Al construir el modelo, cada propiedad pública **sin valor por defecto propio** recibe el neutro de
su tipo:
| Tipo | Inicial |
|---|---|
| `?X` | `null` |
| `string` | `''` |
| `int` / `float` | `0` / `0.0` |
| `bool` | `false` |
| `array` | `[]` |
| `DateTimeImmutable` | `new DateTimeImmutable('now')` |
Los valores que declares explícitamente (`public bool $activo = true;`) **nunca** se sobrescriben.
### Probar que un modelo es válido
```php
Usuario::metadata(); // lanza MetadataException si el modelo está mal declarado
```
---
## 3. Tipos y conversiones
### Al leer de la base (`Repository::find` y compañía)
Lo que llega de PDO es casi siempre `string` o `null`. El ORM lo convierte al tipo PHP declarado:
| Declaras | Recibes de la BD | Obtienes |
|---|---|---|
| `int` | `'42'` | `42` (int) |
| `float` | `'10.5'` | `10.5` |
| `bool` | `'1'` / `'0'` | `true` / `false` |
| `?string` | `null` | `null` |
| `DateTimeImmutable` | `'2024-01-15 00:00:00'` | `DateTimeImmutable` |
| `BackedEnum` | `'activo'` | la instancia del enum |
### Al escribir desde código (`hydrate` / `set`)
| Declaras | Aceptas | Resultado |
|---|---|---|
| `int` | `int`, string numérica, `bool` | `int` |
| `float` | `float`, string numérica, `int`, `bool` | `float` |
| `bool` | `bool`, `0`/`1`, `'0'`/`'1'`, `'true'`/`'false'` | `bool` |
| `string` | escalar, `Stringable` | `string` |
| `array` | `array`, string JSON | `array` |
| `DateTimeImmutable` | `DateTimeInterface`, string de fecha | `DateTimeImmutable` |
| `BackedEnum` | instancia, o su valor escalar | instancia |
| `Brick\Math\BigDecimal` | `BigDecimal`, numérico, string numérica | `BigDecimal` |
**Un valor que no encaja lanza `InvalidArgumentException`.** Nunca se convierte a `null` en
silencio: eso era la fuente de filas con ceros que nadie escribió.
```php
$usuario->hydrate(['activo' => 'quizas']); // InvalidArgumentException
```
### Enums nativos de PHP
```php
enum Estado: string
{
case Pendiente = 'PENDIENTE';
case Pagada = 'PAGADA';
}
#[Enum(Estado::class)]
public Estado $estado = Estado::Pendiente;
```
El valor viaja como su `value` escalar a la base y se valida en `validate()`.
### `DateTimeImmutable`, no `DateTime`
El tipo mapeado es `DateTimeImmutable`. Un `DateTime` mutable puede modificarse en cualquier punto
de un `toArray()` o de una relación, y produce bugs irreproducibles. Si tu tabla devuelve una fecha,
obtienes un inmutable.
---
## 4. Lectura: buscar filas
Todas las lecturas viven en el `Repository`, que obtienes por modelo:
```php
$repo = $orm->repository(Usuario::class);
```
### Las cuatro formas de leer
```php
// 1. Por clave primaria
$usuario = $repo->findByPk(5); // ?Usuario
$usuario = $repo->findByPkOrFail(5); // Usuario, o RecordNotFoundException
// 2. Primera fila que cumpla criterios
$usuario = $repo->findFirst(['correo' => 'a@x']);
// 3. Todas las filas que cumplan criterios
$usuarios = $repo->find(['activo' => true]);
// 4. Consulta fluida (cuando necesitas más)
$usuarios = $repo->query()->where('activo', true)->orderBy('nombre')->get();
```
### Ordenar y limitar
```php
$repo->find(
criteria: ['activo' => true],
order: [['nombre', 'ASC'], ['codigo', 'DESC']],
limit: 20,
offset: 40,
);
```
Las columnas de `order` se validan: si no existen en el modelo, se descartan. Una dirección
inválida lanza `CriteriaException`.
### Conteos y agregaciones
```php
$repo->count(['activo' => true]); // int
$repo->exists(['correo' => 'a@x']); // bool
$repo->sum('total', ['estado' => 'PAGADA']); // float
$repo->avg('total'); // float
$repo->max('total'); // ?float
$repo->min('total'); // ?float
```
`max` y `min` devuelven `null` si no hay filas; `sum` y `avg` devuelven `0.0`.
### Encontrar o crear
```php
$usuario = $repo->findOrCreate(
criteria: ['correo' => 'a@x'],
values: ['nombre' => 'Ana', 'clave' => 'abc'],
);
```
Busca por `criteria`; si no existe, crea con `values + criteria`. **No es transaccional**: entre el
`SELECT` y el `INSERT` otra petición puede insertar la misma fila. Si eso importa, envuélvelo en
`$orm->transaction()` o apóyate en un índice único.
---
## 5. Condiciones de filtro
Un criterio es un array `['columna' => valor]` combinado con `AND`. Puedes usar el nombre de la
propiedad o el de la columna; si usas una clave que no existe, la excepción lista las válidas.
```php
$repo->find([
'activo' => true, // col = ?
'codigo' => [1, 2, 3], // col IN (?, ?, ?)
'apodo' => null, // col IS NULL
'nombre' => Cond::like('%ana%'), // operador explícito
]);
```
### Operadores disponibles — `Cond`
```php
use Camelia\Orm\Query\Cond;
Cond::eq($v) // col = ?
Cond::neq($v) // col <> ?
Cond::gt($v) // col > ?
Cond::gte($v) // col >= ?
Cond::lt($v) // col < ?
Cond::lte($v) // col <= ?
Cond::in([...]) // col IN (...)
Cond::notIn([...]) // col NOT IN (...)
Cond::between($a, $b) // col BETWEEN ? AND ?
Cond::notBetween($a, $b)// col NOT BETWEEN ? AND ?
Cond::like('...') // col LIKE ?
Cond::notLike('...') // col NOT LIKE ?
Cond::isNull() // col IS NULL
Cond::isNotNull() // col IS NOT NULL
Cond::raw($sql, [...]) // escape hatch: el SQL se emite literal
```
`Cond` es inmutable: cada método devuelve un objeto nuevo, muévelo en variables.
### Disyunciones (`OR`)
```php
$repo->query()
->whereGroup(function (GroupCond $g): void {
$g->or('correo', Cond::like('%@camelia.dev'));
$g->or('zona', 3);
})
->get();
// WHERE (correo LIKE ? OR zona = ?)
```
Puedes combinar varios grupos:
```php
$repo->query()
->where('activo', true) // AND con el grupo siguiente
->whereGroup(fn (GroupCond $g) => $g->or('nombre', 'Ana'))
->whereGroup(fn (GroupCond $g) => $g->or('zona', 1), 'OR');
// WHERE (activo = ?) AND (nombre = ?) OR (zona = ?)
```
### Por qué no hay `_and()` ni `whereNot()`
`_and(['a','b'])` generaba `col = 'a' AND col = 'b'`, que en SQL es casi siempre falso. Y
`whereNot()` no excluía `NULL` (semántica estándar de SQL), lo que sorprendía a todo el mundo.
- Para conjunción: varias claves del mismo array **ya** son `AND`.
- Para exclusión: `Cond::neq()` o `Cond::notIn()`.
- Para excluir nulls además del valor: `Cond::isNotNull()` en el criterio y `Cond::neq()`.
### Columnas desconocidas
Una clave que no corresponde a ninguna propiedad ni columna lanza `CriteriaException` con la lista
de columnas válidas. Es la única regla de validación de identificadores; no hay regex de escape que
pueda colarse.
---
## 6. Escritura: guardar filas
### Las dos formas
```php
// 1. Decides tú: save() inserta o actualiza según la PK
$repo->save($usuario);
// 2. Afirmas que la fila existe
$repo->update($usuario);
```
| Método | Cuándo usarlo | Lanza si |
|---|---|---|
| `save($model)` | No sabes (o no te importa) si la fila existe | el modelo no valida |
| `update($model)` | La fila ya existe y quieres sobreescribirla | PK vacía, modelo parcial, no valida |
| `create($values)` | Crear desde un array sin instanciar | no valida |
| `patch($pk, $values)` | Actualizar **solo algunas columnas** | columnas desconocidas |
| `delete($model)` | Borrar por la PK del modelo | PK vacía |
| `remove($pk)` | Borrar por clave, sin instanciar | — |
### Lo único que debes recordar sobre `update`
**`update()` escribe la fila completa.** No hay *dirty tracking*: el modelo es la verdad sobre la
fila. Si hiciste `hydrate` con dos campos, los demás se escriben con su valor en memoria.
```php
$usuario = $repo->findByPk(5); // fila completa
$usuario->nombre = 'Bea';
$repo->update($usuario); // escribe TODAS las columnas
```
Para actualizar una sola columna, usa `patch`:
```php
$repo->patch(5, ['nombre' => 'Bea']); // UPDATE usuarios SET nombre = ? WHERE codigo = ?
```
### Actualizar sin leer
```php
$repo->patch(5, ['activo' => false]);
$repo->remove(5); // true si borró una fila
```
`patch` acepta claves por propiedad o por columna, y aplica el mismo casting que `hydrate`.
### Insertar y obtener la clave autogenerada
```php
$usuario = $repo->create(['nombre' => 'Ana', 'correo' => 'a@x', 'clave' => 'abc']);
$usuario->codigo; // 42, ya asignado
```
Si declaras `#[AutoIncrement]`, tras el `INSERT` el ORM asigna el `lastInsertId` a la propiedad PK.
### Copiar un registro
```php
$copia = $usuario->replicate(); // misma fila lógica, PK vacía
$repo->save($copia); // INSERT de una fila nueva
```
### Modelos parciales
Si leíste con `select()` (columnas restringidas), el modelo queda marcado como parcial:
```php
$parcial = $repo->query()->select('codigo', 'nombre')->get()[0];
$parcial->isPartial(); // true
$repo->update($parcial); // PartialModelException
$repo->patch($parcial->codigo, ['nombre' => 'X']); // ✅ la vía correcta
```
Esto impide el bug clásico: escribir valores neutros en columnas que nunca leíste.
### Hooks
```php
final class Factura extends Model
{
protected function beforeInsert(): void
{
$this->creadoEn = new \DateTimeImmutable('now');
}
protected function beforeUpdate(): void
{
$this->modificadoEn = new \DateTimeImmutable('now');
}
}
```
Solo existen esas dos fases. Para lo demás (auditoría, notificaciones), usa `AuditListener`
([§13](#13-extensiones-auditoría-logs-reloj)).
---
## 7. Validación
Solo tres reglas, las que se declaran con atributos:
```php
#[Required]
public string $nombre = '';
#[Enum(Estado::class)]
public Estado $estado = Estado::Pendiente;
#[MaxLength(150)]
public string $correo = '';
```
| Regla | Disparador | Mensaje |
|---|---|---|
| `#[Required]` | valor `null` o `''` | `El campo {propiedad} es requerido` |
| `#[Enum]` | valor no es instancia del enum | `El valor de {propiedad} no es válido` |
| `#[MaxLength(n)]` | `mb_strlen > n` | `El campo {propiedad} supera {n} caracteres` |
### Comprobar sin escribir
```php
$errores = $usuario->validate(); // ['nombre' => ['El campo nombre es requerido']]
$usuario->isValid(); // bool
```
### La excepción
`save` / `update` / `create` validan y lanzan `ValidationException` con **todos** los errores
agrupados, no el primero:
```php
try {
$repo->save($usuario);
} catch (ValidationException $e) {
$e->errors(); // array<string, list<string>>
$e->model(); // FQCN del modelo
}
```
Los mensajes están en español en el código fuente. Si necesitas otro idioma, traduce en tu capa de
presentación a partir de `errors()`, que te da las claves por propiedad.
---
## 8. Relaciones
### Declaración
```php
use Camelia\Orm\Attribute\{TableName, PrimaryKey, AutoIncrement, BelongsTo, HasMany};
#[TableName('facturas')]
final class Factura extends Model
{
#[PrimaryKey, AutoIncrement]
public ?int $codigo = null;
public int $usuarioCodigo = 0; // columna usuario_codigo
#[BelongsTo(Usuario::class, foreignKey: 'usuarioCodigo')]
public ?Usuario $usuario = null;
/** @var array<int, Detalle> */
#[HasMany(Detalle::class, foreignKey: 'facturaCodigo')]
public array $detalles = [];
}
```
| Atributo | Dónde está la FK | Cuántos carga |
|---|---|---|
| `#[BelongsTo(Clase, foreignKey: 'prop')]` | en la tabla **actual** | 1 |
| `#[HasOne(Clase, foreignKey: 'prop')]` | en la tabla **relacionada** | 1 |
| `#[HasMany(Clase, foreignKey: 'prop')]` | en la tabla **relacionada** | N |
| `#[BelongsToMany(Clase, through: 'pivote', foreignPivotKey: 'a', relatedPivotKey: 'b')]` | tabla pivote | N |
**La propiedad lleva el nombre del rol**, sin sufijos: `$usuario`, no `$usuarioRel`. La propiedad FK
lleva el sufijo `Codigo`: `$usuarioCodigo`, que coincide con el nombre de su columna.
### No hay lazy loading
```php
$factura = $repo->findByPk(1);
$factura->usuario; // null: no se cargó
```
La propiedad empieza con su valor inicial y **solo** cambia por carga explícita o eager loading.
Esto elimina la clase de bugs más difícil de rastrear de los ORM con proxies (`__get` mágico).
### Cargar una relación
```php
// En una instancia
$repo->refreshRelations($factura, ['usuario']);
// Todas las relaciones declaradas
$repo->refreshRelations($factura);
```
### Eager loading (sin N+1)
```php
// Una relación
$repo->find(with: ['usuario']);
// Rutas anidadas
$repo->find(with: ['usuario', 'usuario.ciudad']);
// Anidado explícito con array
$repo->find(with: ['usuario' => ['ciudad', 'zona']]);
// Todas las relaciones de primer nivel (y solo esas)
$repo->find(with: true);
```
Garantías:
- **Una consulta por relación y nivel.** Cargar `usuario` en 100 facturas hace 1 consulta extra, no
100.
- `with: true` carga **solo** el primer nivel. No arrastra niveles profundos por sorpresa.
- Una relación declarada que no existe lanza `MetadataException`, aunque no haya filas.
- Límite duro de **3 niveles** de anidamiento; superarlo lanza `ConfigurationException`. Si
necesitas más, compón llamadas a `refreshRelations()`.
---
## 9. Paginación
```php
$page = $repo->page(
criteria: ['activo' => true],
order: [['nombre', 'ASC']],
page: 2,
perPage: 25,
);
```
```php
$page->items; // list<Model>
$page->page; // 2
$page->perPage; // 25
$page->total; // 137
$page->totalPages; // 6 (siempre int)
$page->hasNext(); // true
$page->hasPrev(); // true
```
También desde una consulta fluida:
```php
$repo->query()->where('activo', true)->page(page: 1, perPage: 50);
```
**Entradas fuera de rango se corrigen, no se ignoran:** `page < 1` → `1`; `perPage` se acota a
`[1, 1000]`. La librería es tolerante en la frontera y estricta en el interior.
`$page->toArray()` devuelve claves en `snake_case` (`per_page`, `total_pages`, `has_next`), listas
para un payload HTTP.
---
## 10. Transacciones
```php
use Camelia\Orm\Orm;
$orm->transaction(function (Orm $orm): void {
$usuarios = $orm->repository(Usuario::class);
$facturas = $orm->repository(Factura::class);
$usuarios->save($u);
$facturas->save($f);
});
```
- Se anidan con **savepoints**.
- Si el callback lanza, hace `rollBack` y **repropaga la excepción original** (no la envuelve).
- Devuelve lo que devuelva el callback.
```php
$id = $orm->transaction(fn () => $orm->repository(Usuario::class)->create([...])->codigo);
```
Las operaciones de la librería **no** abren transacciones por su cuenta. `findOrCreate` no es
transaccional: si lo necesitas, envuélvelo.
---
## 11. Serialización a JSON
```php
$usuario->toArray(); // columnas escribibles + relaciones cargadas
$usuario->toJson(); // JSON con pretty-print y sin escapar unicode ni slashes
$usuario->toJson(JSON_THROW_ON_ERROR); // flags extra para json_encode
$page->toArray(); // payload de paginación, snake_case
$page->toJson();
```
Reglas de conversión:
| Tipo | En JSON |
|---|---|
| `DateTimeImmutable` | string `DATE_ATOM` (`2024-01-15T00:00:00+00:00`) |
| `BackedEnum` | su `value` escalar |
| `BigDecimal` | string (no objeto: `json_encode` fallaría o truncaría) |
| Relación cargada | objeto anidado o array de objetos |
| Relación no cargada | `null` / `[]` |
Solo se serializan **columnas escribibles** y relaciones. La PK no está en `toArray()`; si necesitas
exponerla, añádela con `array_merge(['codigo' => $u->codigo], $u->toArray())` o serializa a mano.
---
## 12. Manejo de errores
**Ninguna lectura devuelve `[]` ante un fallo.** Todo error de base lanza. La regla anterior
("las lecturas degradan") convertía un fallo de conexión en un resultado vacío indistinguible de
"no hay filas".
```
OrmException (extends RuntimeException)
├── ConfigurationException configuración o entorno inválido
├── MetadataException modelo mal declarado
├── CriteriaException columna desconocida / operando inválido
├── ValidationException validate() no vacío → errors(), model()
├── PartialModelException escritura sobre modelo parcial
├── RecordNotFoundException findByPkOrFail / firstOrFail
└── DatabaseException todo fallo SQL → sql(), params(), context()
├── DuplicateKeyException clave única o PK duplicada
├── ForeignKeyViolationException FK rota
└── LockTimeoutException deadlock o lock wait timeout
```
### Capturar por intención
```php
use Camelia\Orm\Exception\{DatabaseException, DuplicateKeyException};
try {
$repo->save($usuario);
} catch (DuplicateKeyException) {
return response()->json(['error' => 'correo duplicado'], 409);
} catch (DatabaseException $e) {
$logger->error('fallo de BD', ['sql' => $e->sql(), 'params' => $e->params()]);
throw $e;
}
```
### Degradar a propósito
Si de verdad quieres tolerar un fallo en una lectura concreta, hazlo explícito en **tu** capa:
```php
try {
$lista = $repo->find(['activo' => true]);
} catch (DatabaseException) {
$lista = [];
}
```
`DatabaseException` expone `sql()`, `params()` y `context()` (`'read'` o `'write'`) para logging.
---
## 13. Extensiones: auditoría, logs, reloj
Todas son interfaces que tú implementas. La librería no trae ninguna implementación concreta.
### Auditoría
```php
use Camelia\Orm\Persistence\AuditListener;
final class Auditoria implements AuditListener
{
public function onWrite(
string $table,
int|string $pk,
string $action, // 'insert' | 'update' | 'delete'
?array $before, // null en insert
array $after, // [] en delete
): void {
// escribe donde tú decidas
}
}
$orm = Orm::fromArray([... , 'auditListener' => new Auditoria()]);
```
Se invoca **tras** un `save`/`update`/`delete` exitoso. El `$before` solo se consulta si hay
listener registrado, así que sin auditoría no cuesta una consulta extra.
### Logging (PSR-3)
```php
$orm = Orm::fromArray([... , 'logger' => $psrLogger, 'slowQueryMs' => 200]);
```
> **Estado actual: no implementado.** `logger` y `slowQueryMs` se aceptan y se exponen por
> `Orm::logger()` / `Orm::slowQueryMs()`, pero **ningún componente los lee todavía**: no hay logging
> automático de SQL lento ni de errores. La librería nunca llama a `error_log()` global, así que sin
> logger simplemente no hay logs. Instrumenta en tu capa si lo necesitas hoy; los parámetros están
> reservados para cuando el soporte se implemente, sin romper la firma de `fromArray`.
### Reloj
```php
use Camelia\Orm\Support\Clock;
$orm = Orm::fromArray([... , 'clock' => $miReloj]);
```
> **Estado actual:** igual que el logger, `clock` se almacena y `Orm::clock()` lo expone, pero el
> ORM no lo usa internamente (no hay timestamps automáticos). Úsalo en tus propios hooks
> (`beforeInsert`) pasando el reloj al modelo, o inyéctalo en tu código de dominio.
---
## 14. Testing de código que usa el ORM
### Tests de modelos sin base de datos
```php
$usuario = (new Usuario())->hydrate(['nombre' => 'Ana', 'clave' => 'abc']);
self::assertSame('Ana', $usuario->nombre);
self::assertTrue($usuario->isValid());
```
`Model` **no** importa `Query` ni `Connection`. Puedes construir y validar un modelo sin conexión.
### Tests de repositorio con doble de conexión
Implementa `Camelia\Orm\Connection\Connection` y registra lo que llega:
```php
use Camelia\Orm\Connection\Connection;
final class FakeConnection implements Connection
{
public array $executed = [];
public array $rows = [];
public function execute(string $sql, array $params = []): int
{
$this->executed[] = ['sql' => $sql, 'params' => $params];
return 1;
}
public function select(string $sql, array $params = []): array
{
return $this->rows;
}
public function scalar(string $sql, array $params = []): mixed { return null; }
public function lastInsertId(): string { return '1'; }
public function begin(): void {}
public function commit(): void {}
public function rollBack(): void {}
public function inTransaction(): bool { return false; }
public function driver(): string { return 'fake'; }
}
$repo = new Camelia\Orm\Repository(new FakeConnection(), Usuario::class);
```
### Aserciones sobre SQL
Para verificar que una consulta se construye bien, no ejecutes; compara `toSql()`:
```php
$sql = $repo->query()->where('activo', true)->orderByDesc('nombre')->toSql();
self::assertSame('SELECT `codigo`, ... FROM `usuarios` WHERE (`activo` = ?) ORDER BY ... DESC', $sql['sql']);
self::assertSame([true], $sql['params']);
```
Es la única forma de probar un compilador SQL sin base de datos.
### Limpiar la caché de metadatos
Los metadatos se leen una vez por proceso. Si un test declara un modelo distinto con la misma clase:
```php
Model::clearMetadataCache();
```
---
## 15. Recetas frecuentes
### Consulta con búsqueda y paginación desde HTTP
```php
$criteria = ['activo' => true];
if ($buscar = $request->get('q')) {
$criteria['nombre'] = Cond::like('%' . $buscar . '%');
}
$page = $orm->repository(Usuario::class)->page(
criteria: $criteria,
order: [['nombre', 'ASC']],
page: (int) ($request->get('page') ?? 1),
perPage: 25,
);
return response()->json($page->toArray());
```
### Crear desde un payload HTTP respetando campos protegidos
```php
$usuario = $repo->create($request->all()); // #[Guarded] se ignora automáticamente
```
Si quieres que un campo protegido en el payload sea un error en lugar de ignorarse:
```php
$usuario = new Usuario();
$usuario->hydrateStrict($payload); // InvalidArgumentException si viene un #[Guarded]
$repo->save($usuario);
```
### Listado con sus relaciones en una sola pasada
```php
$facturas = $repo->find(
criteria: ['usuarioCodigo' => $id],
with: ['detalles'],
);
```
### Borrado protegido por transacción
```php
$orm->transaction(function (Orm $orm) use ($usuario): void {
$orm->repository(Factura::class)->remove($usuario->codigo);
$orm->repository(Usuario::class)->delete($usuario);
});
```
---
## 16. Trampas y errores comunes
| Síntoma | Causa | Solución |
|---|---|---|
| `MetadataException [M3]` | Ninguna o varias propiedades con `#[PrimaryKey]` | Declara exactamente una |
| `MetadataException [M2]` | Falta `#[TableName]` | Añádelo, no hay fallback |
| `MetadataException [M7]` | Dos propiedades a la misma columna | Renombra una con `#[Column]` |
| `CriteriaException: Unknown column` | Clave de criterio que no existe | Revisa el mensaje: lista las válidas |
| `PartialModelException` | `update`/`save` sobre un modelo de `select()` | Usa `patch()` |
| Columna sobrescrita con valor vacío | `update()` escribe la fila completa | Usa `patch()` para cambios puntuales |
| `ConfigurationException: ERRMODE` | `PDO` con modo silencioso | Usa `ERRMODE_EXCEPTION` |
| Relación siempre `null` | No hay lazy loading | Carga con `with:` o `refreshRelations()` |
| Relación llega sin datos pero la fila existe | FK apuntando a la propiedad equivocada | `foreignKey` debe ser el **nombre de la propiedad** |
| `ConfigurationException: depth` | Más de 3 niveles en `with` | Compón `refreshRelations()` |
| `ValidationException` con varios errores | Varias reglas fallando | Es intencional: `errors()` los agrupa |
### Diferencias con otros ORM
Si vienes de Laravel/Eloquent o de Doctrine, estos puntos te van a sorprender:
| Eloquent | camelia/orm |
|---|---|
| `find()` busca por PK | `find()` busca por criterios; por PK es `findByPk()` |
| `save()` hace dirty tracking | No hay dirty tracking: `update()` escribe la fila completa |
| Relaciones lazy por defecto | Sin lazy: carga explícita o `with:` |
| `->update()` sin instanciar | `patch($pk, $values)` |
| Errores a veces silenciosos | Todo lanza |
| `Model::create()` estático | `$repo->create()` |
---
## 17. Referencia de API
### `Orm`
| Método | Devuelve |
|---|---|
| `fromArray(array $options): self` | Conexión PDO nueva |
| `fromEnv(): self` | Conexión desde `CAMELIA_DB_*` |
| `fromPdo(PDO $pdo): self` | Envuelve un PDO existente |
| `fromConnection(Connection $c, array $o = []): self` | Inyecta transporte |
| `repository(string $class): Repository` | Repositorio memoizado por clase |
| `transaction(callable $cb): mixed` | Ejecuta en transacción (anidable) |
| `connection(): Connection` | Transporte |
| `dialect(): Dialect` | Dialecto SQL |
| `clock(): Clock` | Reloj |
| `logger(): ?LoggerInterface` | Logger o `null` |
| `slowQueryMs(): int` | Umbral de SQL lento |
### `Repository`
Lecturas:
| Método | Devuelve |
|---|---|
| `find(array $criteria = [], array $order = [], ?int $limit = null, ?int $offset = null, bool\|array $with = false)` | `list<Model>` |
| `findFirst(array $criteria = [], array $order = [], bool\|array $with = false)` | `?Model` |
| `findByPk(int\|string $pk, bool\|array $with = false)` | `?Model` |
| `findByPkOrFail(int\|string $pk, bool\|array $with = false)` | `Model` |
| `findOrCreate(array $criteria, array $values = [])` | `Model` |
| `count(array $criteria = [])` | `int` |
| `exists(array $criteria = [])` | `bool` |
| `sum/avg(string $column, array $criteria = [])` | `float` |
| `max/min(string $column, array $criteria = [])` | `?float` |
| `page(array $criteria = [], array $order = [], int $page = 1, int $perPage = 20)` | `Page` |
| `query()` | `Query` |
| `metadata()` | `ClassMetadata` |
| `refreshRelations(Model $model, array $only = [])` | `void` |
Escrituras:
| Método | Devuelve |
|---|---|
| `save(Model $model)` | `int\|string` (PK) |
| `create(array $values = [])` | `Model` |
| `update(Model $model)` | `void` |
| `delete(Model $model)` | `void` |
| `patch(int\|string $pk, array $values)` | `void` |
| `remove(int\|string $pk)` | `bool` |
### `Query` (inmutable)
Constructor: `$repo->query()`.
| Grupo | Métodos |
|---|---|
| Filtros | `where`, `whereIn`, `whereNotIn`, `whereNull`, `whereNotNull`, `whereGroup` |
| Orden | `orderBy`, `orderByDesc` |
| Límites | `limit`, `offset` |
| Proyección | `select(string ...$columns)` |
| Relaciones | `with(bool\|string\|array ...$relations)` |
| Terminales | `get`, `first`, `firstOrFail`, `count`, `exists`, `sum`, `avg`, `max`, `min`, `pluck`, `page`, `toSql` |
`toSql()` devuelve `['sql' => string, 'params' => list<mixed>]`.
### `Model`
| Método | Devuelve |
|---|---|
| `hydrate(array $data)` | `static` |
| `hydrateStrict(array $data)` | `static` (lanza si viene un `#[Guarded]`) |
| `toArray(?array $only = null)` | `array<string, mixed>` |
| `toJson(int $flags = 0)` | `string` |
| `validate()` | `array<string, list<string>>` |
| `isValid()` | `bool` |
| `isPartial()` / `markPartial(bool = true)` | `bool` / `void` |
| `replicate()` | `static` |
| `get(string $property)` / `set(string $property, mixed $value)` | `mixed` / `static` |
| `metadata()` (estático) | `ClassMetadata` |
| `clearMetadataCache()` (estático) | `void` |
Hooks sobreescribibles: `beforeInsert()`, `beforeUpdate()` (ambos `protected`).
### `Cond`
`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `between`, `notBetween`, `like`, `notLike`,
`isNull`, `isNotNull`, `raw($sql, array $params = [])`.
### `Page`
Propiedades: `items`, `page`, `perPage`, `total`, `totalPages`.
Métodos: `hasNext()`, `hasPrev()`, `toArray()`, `toJson()`.
Constantes: `MIN_PER_PAGE = 1`, `MAX_PER_PAGE = 1000`.
### Atributos
| Atributo | Target | Efecto |
|---|---|---|
| `#[TableName(string)]` | clase | Tabla destino (obligatorio) |
| `#[PrimaryKey]` | prop | Marca la PK (obligatorio, exactamente uno) |
| `#[AutoIncrement]` | prop | PK generada por la BD |
| `#[Column(string)]` | prop | Nombre de columna explícito |
| `#[Guarded]` | prop | Excluida de `hydrate()` |
| `#[Ignore]` | prop | Excluida de persistencia y de `hydrate()` |
| `#[Required]` | prop | Validación de no vacío |
| `#[Enum(BackedEnum::class)]` | prop | Casting y validación contra el enum |
| `#[Nullable]` | prop | Fuerza nulabilidad cuando el tipo no la expresa |
| `#[MaxLength(int)]` | prop | Validación de longitud |
| `#[Length(int)]` | prop | **Sin efecto**: reservado para generación de DDL (no implementada) |
| `#[Precision(int, int)]` | prop | **Sin efecto**: reservado para DDL |
| `#[Unique]` / `#[UniqueGroup(string)]` | prop | **Sin efecto**: reservado para DDL |
| `#[Index(string $order = 'ASC')]` | prop | Marcado como indexado en metadatos; **no** genera DDL |
| `#[BelongsTo / HasOne / HasMany / BelongsToMany]` | prop | Relación |
### `ClassMetadata`
`table()`, `primaryKey()`, `primaryKeyColumn()`, `column(string)`, `property(string)`,
`hasProperty(string)`, `hasColumn(string)`, `propertyMetadata(string)`, `properties()`,
`relations()`, `indexed()`, `writable()`, `resolveProperty(string)`, `knownKeys()`.
`PropertyMetadata` expone: `name`, `column`, `type`, `enumClass`, `relation`, `declaringClass`,
`nullable`, `ignored`, `guarded`, `primaryKey`, `autoIncrement`, `required`, `indexed`, `maxLength`.
Métodos: `isWritable()`, `isRelation()`.
### `Connection`
`execute(string $sql, array $params = []): int`, `select(...): array`,
`scalar(...): mixed`, `lastInsertId(): string`, `begin()`, `commit()`, `rollBack()`,
`inTransaction(): bool`, `driver(): string`.
---
## Apéndice: por dónde seguir
| Documento | Contenido |
|---|---|
| [`README.md`](README.md) | Arranque mínimo y comandos de desarrollo |
| [`docs/GUIA-PROGRAMADOR.md`](docs/GUIA-PROGRAMADOR.md) | Guía completa por tareas, recetas y referencia de API |
| [`especificaciones-orm.md`](especificaciones-orm.md) | Contrato de diseño completo, glosario normativo |
| [`CHANGELOG.md`](CHANGELOG.md) | Cambios por versión |
| [`AGENTS.md`](AGENTS.md) | Convenciones para contribuir al código de la librería |