Files
camelia-orm/docs/GUIA-PROGRAMADOR.md
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

34 KiB

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. Para el arranque rápido, el README.

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
  2. Definir un modelo
  3. Tipos y conversiones
  4. Lectura: buscar filas
  5. Condiciones de filtro
  6. Escritura: guardar filas
  7. Validación
  8. Relaciones
  9. Paginación
  10. Transacciones
  11. Serialización a JSON
  12. Manejo de errores
  13. Extensiones: auditoría, logs, reloj
  14. Testing de código que usa el ORM
  15. Recetas frecuentes
  16. Trampas y errores comunes
  17. Referencia de API

1. Instalación y arranque

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.

use Camelia\Orm\Orm;

$orm = Orm::fromArray([
    'host'     => '127.0.0.1',
    'port'     => 3306,
    'user'     => 'app',
    'password' => 'secret',
    'database' => 'erp',
]);

Desde variables de entorno

$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

$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.

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

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]:

#[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

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ó.

$usuario->hydrate(['activo' => 'quizas']);   // InvalidArgumentException

Enums nativos de 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:

$repo = $orm->repository(Usuario::class);

Las cuatro formas de leer

// 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

$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

$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

$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.

$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

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)

$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:

$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

// 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.

$usuario = $repo->findByPk(5);   // fila completa
$usuario->nombre = 'Bea';
$repo->update($usuario);         // escribe TODAS las columnas

Para actualizar una sola columna, usa patch:

$repo->patch(5, ['nombre' => 'Bea']);   // UPDATE usuarios SET nombre = ? WHERE codigo = ?

Actualizar sin leer

$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

$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

$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:

$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

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).


7. Validación

Solo tres reglas, las que se declaran con atributos:

#[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

$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:

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

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

$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

// En una instancia
$repo->refreshRelations($factura, ['usuario']);

// Todas las relaciones declaradas
$repo->refreshRelations($factura);

Eager loading (sin N+1)

// 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

$page = $repo->page(
    criteria: ['activo' => true],
    order:    [['nombre', 'ASC']],
    page:     2,
    perPage:  25,
);
$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:

$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

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.
$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

$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

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:

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

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)

$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

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

$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:

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():

$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:

Model::clearMetadataCache();

15. Recetas frecuentes

Consulta con búsqueda y paginación desde HTTP

$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

$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:

$usuario = new Usuario();
$usuario->hydrateStrict($payload);           // InvalidArgumentException si viene un #[Guarded]
$repo->save($usuario);

Listado con sus relaciones en una sola pasada

$facturas = $repo->find(
    criteria: ['usuarioCodigo' => $id],
    with:     ['detalles'],
);

Borrado protegido por transacción

$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 Arranque mínimo y comandos de desarrollo
docs/GUIA-PROGRAMADOR.md Guía completa por tareas, recetas y referencia de API
especificaciones-orm.md Contrato de diseño completo, glosario normativo
CHANGELOG.md Cambios por versión
AGENTS.md Convenciones para contribuir al código de la librería