# 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 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> $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 */ #[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 $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` | | `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]`. ### `Model` | Método | Devuelve | |---|---| | `hydrate(array $data)` | `static` | | `hydrateStrict(array $data)` | `static` (lanza si viene un `#[Guarded]`) | | `toArray(?array $only = null)` | `array` | | `toJson(int $flags = 0)` | `string` | | `validate()` | `array>` | | `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 |