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.
1100 lines
34 KiB
Markdown
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 |
|