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.
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
- Instalación y arranque
- Definir un modelo
- Tipos y conversiones
- Lectura: buscar filas
- Condiciones de filtro
- Escritura: guardar filas
- Validación
- Relaciones
- Paginación
- Transacciones
- Serialización a JSON
- Manejo de errores
- Extensiones: auditoría, logs, reloj
- Testing de código que usa el ORM
- Recetas frecuentes
- Trampas y errores comunes
- 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()nireset(). Si necesitas otra conexión, crea otroOrm.
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()oCond::notIn(). - Para excluir nulls además del valor:
Cond::isNotNull()en el criterio yCond::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
usuarioen 100 facturas hace 1 consulta extra, no 100. with: truecarga 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 arefreshRelations().
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
rollBacky 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.
loggeryslowQueryMsse aceptan y se exponen porOrm::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 aerror_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 defromArray.
Reloj
use Camelia\Orm\Support\Clock;
$orm = Orm::fromArray([... , 'clock' => $miReloj]);
Estado actual: igual que el logger,
clockse almacena yOrm::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 |