# Especificaciones de `camelia-orm` — librería ORM independiente Documento normativo y **autosuficiente** para construir una librería PHP 8.2+ autónoma, sin dependencia de la aplicación que la consume. Todo lo necesario para implementarla, probarla y publicarla está aquí; no se asume ningún otro documento. > Este documento **define** el contrato. No describe código preexistente. Cuando una decisión de > diseño tenga más de una salida razonable, se explica la elegida y por qué. --- ## 0. Nomenclatura canónica **Este glosario es normativo.** Todo nombre de clase, método, parámetro y atributo del documento proviene de esta tabla. Si algo no está aquí, no existe en la librería. Regla de formación: **el nombre dice qué es, no qué hace de dónde viene.** - **Clases**: sustantivo singular en `PascalCase`. `Model`, no `BaseBean`. `Page`, no `PaginadorResultado`. - **Interfaces**: capacidad, sin prefijo `I` ni sufijo `Interface` cuando el sustantivo ya es un rol. `Clock`, `Dialect`, `Listener`. La excepción es `Connection` (§0.3): ver la nota. - **Métodos de lectura/escritura**: verbo en infinitivo o 3ª persona, nunca gerundio. `find`, no `finding`. Las consultas usan el **prefijo `find`**; las escrituras usan el **verbo SQL directo**. - **Colecciones**: plural. `items`, no `itemList`. `properties()`, no `getPropertyArr()`. - **Booleanos**: predicado afirmativo, `is`/`has`/`can`. `isPartial()`, `hasNext()`. - **Parámetros**: `$criteria` (filtro), `$order` (orden), `$with` (relaciones eager), `$pk` (clave), `$page`/`$perPage` (paginación). **Un nombre, un significado en toda la API.** - **Sin abreviaturas**: `Configuration`, no `Config`; `Metadata`, no `Meta`; `Repository`, no `Repo`. Excepto en **nombres de variable locales de ejemplo** (`$repo`), donde la brevedad del snippet gana. ### 0.1 Cambios de nombre respecto a versiones anteriores del documento | Antes | Ahora | Razón | |---|---|---| | `SqlDialect` (interface) | `Dialect` | El namespace ya es `Query`; `Sql` era redundante | | `CriterionCompiler` | `CriteriaCompiler` | Concierta con el parámetro `$criteria` | | `OrderCompiler` | — (absorbido por `QueryBuilder`) | No hay parámetro `$order` que justifique una clase | | `FluentQuery` | `Query` | Es *la* consulta fluida; el adjetivo no aportaba | | `Repository::findOne()` | `Repository::findFirst()` | `first`/`findFirst` es simbólico; `One` era genérico | | `Repository::find()` (por PK) | `Repository::findByPk()` | `find()` sin argumento mental es ambiguo | | `Repository::findOrFail()` | `Repository::findByPkOrFail()` | Dice **qué** falla: el PK no existe | | `Repository::findAll()` | `Repository::find()` | Es la lectura canónica; `All` sobra | | `Repository::insert/update/delete/save` | `save()` unifica insert/update; `patch`/`remove` van por clave | `insert` era `save` restringido; cuatro métodos para dos operaciones | | `updateByPk` / `deleteByPk` | `patch()` / `remove()` | El sufijo `ByPk` decía *cómo* se identifica, no *qué* hace; y `update` quedaba sobrecargada | | `Model::fill()` | `Model::hydrate()` | `fill` no dice de dónde | ### 0.2 Glosario de términos | Término | Significado exacto en este documento | |---|---| | **Modelo** | Instancia de una clase que extiende `Model`. Solo estado + reglas de forma. | | **Entidad** | Sinónimo de modelo. Se usa indistintamente; no hay dos conceptos. | | **Repositorio** | Objeto `Repository` que ejecuta lectura/escritura para **un** modelo. | | **Criterio** | Array `['columna' => valor\|Cond]`. | | **Cond** | Objeto inmutable que representa un operador SQL sobre una columna. | | **GroupCond** | Acumulador mutable de condiciones dentro de `Query::whereGroup()`; solo existe en ese scope. | | **Query** | Consulta fluida inmutable. Antes llamada `FluentQuery`. | | **Page** | Resultado paginado inmutable. | | **Metadata** | Descripción estática de un modelo derivada por reflexión. | | **Dialect** | Traductor de una operación abstracta a SQL de un motor. | | **Connection** | Abstracción de transporte SQL. Ver §0.3. | | **Persister** | Componente interno que ejecuta escrituras. No es API pública. | | **Parcial** | Modelo hidratado con `select()`: no todas sus columnas fueron leídas. | ### 0.3 Convenciones de sufijos que **no** se usan | Sufijo | Por qué no | |---|---| | `Interface` | El tipo ya lo dice. `Connection` es el caso límite: se conserva el nombre de rol y la interfaz es `Connection`, mientras que la implementación PDO se llama `PdoConnection`. **La implementación lleva el prefijo del driver; la interfaz, el nombre del rol.** | | `Exception` | Excepción obvia por contexto. Se conserva solo donde el nombre sin sufijo sería ambiguo (`MetadataException`). | | `Dto`, `ValueObject`, `Data` | Ruido. | | `Service`, `Manager`, `Handler`, `Helper` | Nombres que no dicen nada. Si lo necesita, está mal dividido. | | `Base` | El prefijo `Base` apunta a herencia para reutilizar código. Aquí se usa composición. | ### 0.4 Nombres prohibidos (aparecen en el legado, no aquí) `SimpleModelBase` · `SimpleModelBaseQueries` · `Conexion` · `EDatabase` · `FilterExpr` · `TraitAuditoriaCambios` · `AuditoriaCambios` · `_in` · `_or` · `_and` · `whereNot` · `getRelated` · `getRelatedMany` · `loadRelations` · `buildData` · `initializeProperties`. --- ## 1. Resumen ejecutivo `camelia-orm` es un ORM ligero de *Active Record* sobre PDO para MariaDB/MySQL, mapeado con atributos PHP. Su objetivo es ser **pequeño de leer, predecible de usar y trivial de mockear**. - **Nombre del paquete:** `camelia/orm` · **autor:** Dr2g Sistemas · **namespace raíz:** `Camelia\Orm` - **PHP:** `>=8.2` · **Extensión:** `pdo_mysql` (obligatoria), `mbstring` (obligatoria) - **Dependencias de runtime:** `psr/log ^3.0` (PSR-3, uso opcional). `brick/math` es `suggest`. - **Dependencias de desarrollo:** `carthage-software/mago ^1.60` (formatter, linter, analyzer), `phpunit/phpunit ^10|^11`, `phpstan/phpstan ^1.11` (nivel 8) - **PSR:** `PSR-4` (`Camelia\Orm\` → `src/`) y `PSR-3` (logging opcional) ### Principios rectores (aplican a cada sección) | Principio | Cómo se materializa en esta librería | |---|---| | **SoC** | Metadatos (reflexión) ⟂ SQL (compilación) ⟂ Ejecución (PDO) ⟂ Estado (entidad) ⟂ Presentación (`toArray`). Ningún componente hace dos de estas cosas. | | **SOLID** | El compilador SQL depende de `Dialect` (interface), no de MySQL. Cada clase tiene una única razón de cambio: `MetadataCache` cachea, `MetadataFactory` reflexiona. Inyectar `Connection` permite sustituir PDO en tests. | | **KISS** | Una sola forma canónica de hacer cada cosa. No existen dos métodos con el mismo nombre y semánticas distintas, ni dos nombres para la misma operación dentro del mismo objeto. | | **DRY** | Un único `CriteriaCompiler` produce `WHERE`+params para criterios; lo usan `find`, `count`, `page` y `Query`. Un único `MetadataCache`. | ### Decisiones de diseño que corrigen el legado Si vienes de la especificación anterior del ORM del ERP, estos cambios son **intencionales**: 1. **Se elimina la duplicación `SimpleModelBase` ↔ `SimpleModelBaseQueries`.** Una sola clase, `Camelia\Orm\Model`, delegando en `Repository` (composición, no herencia de implementaciones). 2. **Se eliminan los helpers globales `_in()`, `_or()`, etc.** Colisionan con el consumidor y violan autosuficiencia. Se reemplazan por una clase estática `Cond` con métodos encadenables. 3. **`manyToMany` funciona o no existe.** La spec de referencia lo documentaba roto. Aquí es un contrato real con tabla pivote declarativa. 4. **No hay "lecturas que degradan".** Silenciar errores SQL es el mayor defecto del diseño previo: un fallo de base se convierte en `[]` y el bug aparece 3 capas arriba. Aquí **todo** error lanza. Para degradar intencionalmente, el consumidor captura. `getOrNull()` está disponible como azúcar explícita para el caso legítimo. 5. **Coherencia de tipos en la salida.** `Page::$totalPages` es `int` siempre. 6. **Se elimina `#[Timestamp]`, `#[OnInsert]`, `#[OnUpdate]`, `#[Description]`, `#[Comment]`, `#[Check]`.** Eran declarativos sin efecto en runtime; su lugar está en el `CREATE TABLE` de la migración, no en atributos PHP que fingen hacer algo. La generación de DDL queda fuera de la librería (§12). ### Fuera de alcance (explícito, no ambiguo) Contenedor DI · migraciones automáticas · lazy loading por proxy · unit of work / identity map · herencia de tabla · soft deletes automáticos · eventos observables · consultas no-SQL · multitenancy · auditoría de cambios (se ofrece como `listener` opcional, §10.3). Si algo de esto se necesita, se implementa **fuera** de la librería, sobre sus hooks públicos. --- ## 2. Mapa de la librería ``` src/ ├── Connection/ │ ├── Connection.php ← interface: rol de transporte SQL │ ├── PdoConnection.php ← implementación PDO │ └── ConnectionFactory.php ← desde array de config o entorno ├── Attribute/ ← atributos sin lógica (§4) ├── Metadata/ │ ├── ClassMetadata.php ← DTO inmutable │ ├── PropertyMetadata.php ← DTO inmutable │ ├── RelationMetadata.php ← DTO inmutable de relación │ ├── MetadataFactory.php ← reflexión → ClassMetadata │ └── MetadataCache.php ← memo por clase ├── Query/ │ ├── Cond.php ← constructores de condiciones (§6.3) │ ├── CriteriaCompiler.php ← (Cond|array) → [sql, params] │ ├── Dialect.php ← interface │ ├── MySqlDialect.php ← única implementación │ ├── QueryBuilder.php ← SELECT/UPDATE/DELETE compilado │ └── Query.php ← consulta fluida inmutable ├── Repository.php ← API pública de lectura y escritura ├── Model.php ← estado + hydrate/toArray/validate ├── Persistence/ │ ├── Persister.php ← INSERT/UPDATE/DELETE (interno) │ ├── AuditListener.php ← interface, sin implementación por defecto │ └── Validator.php ← reglas derivadas de atributos (interno) ├── Pagination/ │ └── Page.php ← resultado paginado inmutable ├── Exception/ ← jerarquía tipada (§11) └── Support/ ← TypeCaster, NameConverter, Clock ``` > El directorio `Schema/` de versiones anteriores del documento **no existe**: la generación de DDL > está fuera de alcance (§12). **Regla de dependencia (verificable con PHPStan):** ``` Model ──► Metadata (DTO) Model ──► Support Repository ──► Query, Metadata, Persistence, Pagination Persistence ──► Query, Metadata, Connection Query ──► Connection, Metadata, Support Metadata, Support, Attribute ──► (nada interno) Exception ──► (nada) ``` `Model` **no** importa `Query` ni `Connection`. La persistencia se invoca vía `Repository`, que el consumidor obtiene de `Orm::repository(ModelX::class)`. Esto es lo que hace la entidad testeable sin base de datos. **Regla de visibilidad:** `Persister`, `Validator`, `CriteriaCompiler`, `QueryBuilder` y `MetadataFactory` son `@internal`. El consumidor toca `Orm`, `Repository`, `Query`, `Page`, `Cond`, `Model`, los atributos y las excepciones. Todo lo demás es implementación. --- ## 3. Arranque: `Orm` Un único objeto raíz. Inmutable, seguro de pasar por constructor. ```php use Camelia\Orm\Orm; $orm = Orm::fromArray([ 'host' => '127.0.0.1', 'port' => 3306, 'user' => 'app', 'password' => '...', 'database' => 'erp', 'charset' => 'utf8mb4', // opcional 'sslCa' => '/ruta/ca.pem', // opcional ]); $repo = $orm->repository(ModelUsuario::class); // Camelia\Orm\Repository $user = $repo->findFirst(['codigo' => 1]); ``` También existe `Orm::fromPdo(PDO $pdo)` y `Orm::fromEnv(): self` (lee `CAMELIA_DB_*`, ver §3.1). Todas convergen en el mismo constructor privado. No hay singleton ni estado estático global. ### 3.1 Variables de entorno (`fromEnv`) | Variable | Obligatoria | |---|---| | `CAMELIA_DB_HOST` | sí | | `CAMELIA_DB_USER` | sí | | `CAMELIA_DB_NAME` | sí | | `CAMELIA_DB_PASS` | sí (puede ser cadena vacía) | | `CAMELIA_DB_PORT` | no (default `3306`) | | `CAMELIA_DB_CHARSET` | no (default `utf8mb4`) | Si falta una obligatoria: `ConfigurationException` con la lista de las que faltan (todas, no la primera). ### 3.2 Configuración de PDO esperada `PdoConnection` impone, sin excepción, `ERRMODE_EXCEPTION`, `FETCH_ASSOC`, `ATTR_EMULATE_PREPARES = false`, `MYSQL_ATTR_SSL_CA` si se pasa en config. Si el `PDO` entregado vía `fromPdo` no está en `ERRMODE_EXCEPTION`, `PdoConnection` falla con `ConfigurationException`: los modos silenciosos son incompatibles con el contrato de §11. --- ## 3. Definir un modelo ```php **Cambio respecto al legado:** `DateTime` se reemplaza por `DateTimeImmutable` como tipo mapeado. > Mutar un `DateTime` inside `toArray()` o desde fuera produce bugs no reproducibles. --- ## 4. Metadatos `MetadataFactory::forClass(string $class): ClassMetadata`, memoizado en `MetadataCache` (`WeakMap` interno, tamaño ilimitado: la JVM ya no es el motivo del límite de 100). ```php final class ClassMetadata { public function table(): string; public function primaryKey(): string; // nombre de PROPIEDAD public function primaryKeyColumn(): string; // nombre de COLUMNA /** @return array indexado por PROPIEDAD */ public function properties(): array; public function column(string $property): string; public function property(string $column): ?string; public function hasProperty(string $property): bool; public function hasColumn(string $column): bool; /** @return list */ public function relations(): array; /** @return list */ public function indexed(): array; /** @return list propiedades escribibles (no ignoradas, no PK) */ public function writable(): array; } final class PropertyMetadata { public string $name; // propiedad PHP public string $column; // columna SQL public string $type; // string|int|float|bool|array|DateTimeImmutable|BackedEnum|BigDecimal|mixed public bool $nullable; public bool $ignored; public bool $guarded; public bool $primaryKey; public bool $autoIncrement; public ?string $enumClass; // BackedEnum::class si se declara public ?RelationMetadata $relation; } final class RelationMetadata { public string $kind; // 'belongsTo'|'hasOne'|'hasMany'|'belongsToMany' public string $relatedClass; // FQCN resuelto public string $foreignKey; // PROPIEDAD del modelo dueño de la FK public ?string $through; // solo belongsToMany: tabla pivote public ?string $foreignPivotKey; public ?string $relatedPivotKey; } ``` **Convención `primaryKey()` vs `primaryKeyColumn()`**: se repite en toda la librería. Un método que dice `...Column()` devuelve columna SQL; sin sufijo devuelve propiedad PHP. Nunca se mezclan. `MetadataCache::clear()` existe **solo** para tests. En producción los metadatos son inmutables por proceso; si los atributos cambian en caliente, hace falta reiniciar. --- ## 5. Atributos Se declaran en `Camelia\Orm\Attribute\*`, todos `#[Attribute(Attribute::TARGET_*) final readonly]` y sin lógica. Un atributo que no se lee en runtime no existe en esta librería. | Atributo | Target | Efecto runtime | |---|---|---| | `#[TableName(string)]` | clase | Nombre de tabla (obligatorio) | | `#[PrimaryKey]` | prop | Marca PK (obligatorio, exactamente uno) | | `#[AutoIncrement]` | prop | Tras `INSERT`, PK se toma de `lastInsertId` | | `#[Column(string)]` | prop | Sustituye la conversión snake_case | | `#[Guarded]` | prop | Excluida de `hydrate()`; **no** de escritura directa | | `#[Ignore]` | prop | Excluida de SELECT/INSERT/UPDATE y de `hydrate()`; la relación se declara con su atributo de §8 | **Nota sobre relaciones:** una propiedad de relación se excluye de la persistencia por llevar su atributo `#[BelongsTo]`/`#[HasOne]`/`#[HasMany]`/`#[BelongsToMany]`, no por `#[Ignore]`. Exigir ambos era redundante y permitía un estado incoherente (relación declarada sin excluir). | `#[Required]` | prop | `validate()` rechaza `null` y `''` | | `#[Enum(BackedEnum::class)]` | prop | Casting + validación contra el enum nativo | | `#[Nullable]` | prop | Fuerza `nullable = true` cuando el tipo PHP no lo expresa (p. ej. `string`) | | `#[Length(int)]` | prop | **Sin efecto** (reservado para DDL no implementado) | | `#[Precision(int, int)]` | prop | **Sin efecto** (reservado para DDL) | | `#[Unique]`, `#[UniqueGroup(string)]` | prop | **Sin efecto** (reservado para DDL) | | `#[Index(string $order = 'ASC')]` | prop | Solo marca `PropertyMetadata::$indexed`; no genera DDL | | `#[MaxLength(int)]` | prop | `validate()` rechaza strings más largos | **Se elimina deliberadamente:** `#[Timestamp]`, `#[OnInsert]`, `#[OnUpdate]`, `#[Description]`, `#[Comment]`, `#[ForeignKey]`, `#[DefaultValue]`, `#[Check]`. La DDL se genera desde tipo PHP + `#[Length]`/`#[Precision]`; lo que un atributo no puede garantizar en runtime no se declara como si lo hiciera. `#[ForeignKey]` se sustituye por el atributo de relación de §8, que sí se usa. --- ## 6. Lectura ### 6.1 API de `Repository` **Regla única:** las lecturas usan el prefijo `find`; las escrituras usan el verbo de destino (`save`, `update`, `delete`, `create`). Un método llamado `find*` nunca escribe. Todas las lecturas toman `array $criteria` (§6.2), o `$pk` cuando el nombre lo dice (`findByPk`). ```php final class Repository { /** @param array $criteria */ public function find(array $criteria = [], array $order = [], ?int $limit = null, ?int $offset = null, bool|array $with = false): array; public function findFirst(array $criteria = [], array $order = [], bool|array $with = false): ?Model; public function findByPk(int|string $pk, bool|array $with = false): ?Model; public function findByPkOrFail(int|string $pk, bool|array $with = false): Model; public function findOrCreate(array $criteria, array $values = []): Model; public function count(array $criteria = []): int; public function exists(array $criteria = []): bool; public function sum(string $column, array $criteria = []): float; public function avg(string $column, array $criteria = []): float; public function max(string $column, array $criteria = []): ?float; public function min(string $column, array $criteria = []): ?float; public function page(array $criteria = [], array $order = [], int $page = 1, int $perPage = 20): Page; public function query(): Query; } ``` **Por qué `find` y no `findAll`.** `find()` es la lectura canónica; "todas las que cumplan el criterio" es lo que ya implica. `findAll` con `$limit = 10` era contradictorio: el nombre prometía todas y la firma limitaba. Un nombre, una promesa. **Por qué `findFirst` y no `findOne`.** `first` describe posición; `one` describe cantidad. Con `$order`, "el primero" es exacto. **Por qué `findByPk` existe además de `find`.** `find(['codigo' => 5])` y `findByPk(5)` producirían el mismo SQL, y eso es **DRY por la vía correcta**: `findByPk` es azúcar documentada sobre `find` con el criterio de PK, porque leer por clave es la operación más frecuente y merece nombre propio. No son dos implementaciones: `findByPk` construye un criterio y delega. Ninguno de estos métodos captura `PDOException`. Ver §11. ### 6.2 Criterios Forma: `['propiedad_o_columna' => valor]`, combinados con `AND`. | Valor | SQL | |---|---| | escalar | `col = ?` | | `array` | `col IN (?, ?, ...)`; array vacío → `1 = 0` (nunca se ignora en silencio) | | `null` | `col IS NULL` | | `Cond` | según su operador (§6.3) | **Validación de identificadores**: la clave debe existir como propiedad o columna declarada en `ClassMetadata`. Si no, `CriteriaException::unknownColumn($model, $key)` con la lista de columnas válidas en el mensaje. No hay regex de escape como criterio de aceptación: la pertenencia al metadata es la única regla y es más estricta que cualquier regex. ### 6.3 Condiciones — `Cond` Clase estática, **sin funciones globales**. Cada método devuelve un objeto `Cond` inmutable. ```php use Camelia\Orm\Query\Cond; $repo->find([ 'activo' => true, 'codigo' => Cond::in([1, 2, 3]), 'creadoEn' => Cond::between('2024-01-01', '2024-12-31'), 'nombre' => Cond::like('%ana%'), 'eliminado' => Cond::isNull(), ]); // Grupos (solo en Query, §6.4): $q->whereGroup(function (GroupCond $group) { $group->or('correo', Cond::like('%@camelia.dev')); $group->or('zona', 3); }); ``` `GroupCond` es **la única entrada mutable** de la API, y por diseño: acumula condiciones mientras se ejecuta el closure. Vive solo dentro de la llamada; nunca se expone fuera de ella. | Método | SQL | |---|---| | `Cond::eq($v)` | `col = ?` *(explícito; por defecto un escalar ya lo hace)* | | `Cond::neq($v)` | `col <> ?` | | `Cond::gt/gte/lt/lte($v)` | `col > >= < <= ?` | | `Cond::in(array $v)` | `col IN (...)` | | `Cond::notIn(array $v)` | `col NOT IN (...)` | | `Cond::between($a, $b)` | `col BETWEEN ? AND ?` | | `Cond::notBetween($a, $b)` | `col NOT BETWEEN ? AND ?` | | `Cond::like(string $v)` | `col LIKE ?` | | `Cond::notLike(string $v)` | `col NOT LIKE ?` | | `Cond::isNull()` | `col IS NULL` | | `Cond::isNotNull()` | `col IS NOT NULL` | | `Cond::raw(string $sql, array $params)` | `()` — **escape hatch documentado**, el identificador no se valida | **Se eliminan `_and` y `_or` de la spec anterior.** `_and(['a','b'])` generaba `col = 'a' AND col = 'b'` (siempre falso), violación directa de KISS: existía una API cuyo comportamiento nadie podía predecir. Para disyunciones, `whereGroup`/`or`. Para conjunciones, varias claves del mismo array ya son `AND`. **`whereNot` también se elimina como atajo.** `NOT (col = ?)` excluía `NULL` por semántica SQL, lo que sorprendía a todo el mundo. La forma explícita es `Cond::neq()` o `Cond::notIn()`; quien quiera excluir nulls lo escribe (`Cond::isNotNull()` + `neq`, o `raw`). ### 6.4 `Query` ```php $q = $repo->query(); $q->where('activo', true) // igual que el array de criterios ->whereIn('zona', [1, 2]) ->whereGroup(fn(GroupCond $g) => $g->or(...)->and(...)) ->orderBy('nombre') ->orderByDesc('creadoEn') ->limit(20)->offset(40) ->with('empresa', 'empresa.ciudad') // §8.3 ->get(); // Model[] $q->first(); // ?Model $q->count(); // int $q->exists(); // bool $q->page(page: 2, perPage: 50); // Page $q->pluck('nombre'); // list $q->select('codigo', 'nombre')->get(); // hidrata solo esas columnas $q->toSql(); // ['sql' => ..., 'params' => ...] para debug ``` **Terminales y su correspondencia con `Repository`** — mismo nombre para la misma operación, sin excepción: | `Query` | `Repository` | Retorno | |---|---|---| | `get()` | `find()` | `Model[]` | | `first()` | `findFirst()` | `?Model` | | `firstOrFail()` | `findByPkOrFail()` (solo por PK) | `Model` | | `count()` | `count()` | `int` | | `exists()` | `exists()` | `bool` | | `sum()`/`avg()`/`max()`/`min()` | idem | `float`/`?float` | | `page()` | `page()` | `Page` | | `pluck()` | — | `list` | | `toSql()` | — | `array{sql:string, params:array}` | `get`/`first` son los nombres del *builder* (`get` = "dame lo construido"); `find`/`findFirst` los del *repositorio*. La diferencia es de rol, no de semántica: no hay dos comportamientos, hay dos superficies. Lo que **no** existe es un mismo nombre con dos comportamientos, ni dos nombres para un mismo comportamiento en el mismo objeto. **No hay doble camino.** `find`, `findFirst`, `count`, `page` construyen un `Query` internamente y lo ejecutan. La especificación anterior describía un "enrutamiento" entre ruta avanzada y `Repository` según qué método se llamara; esa distinción desaparece porque existe un solo compilador. `Query` es **inmutable**: cada método devuelve una copia. Esto evita que un query se contamine al reutilizarlo en tests, que era el bug más caro de depurar en el legado mutable. `select()` restringe columnas: las propiedades no seleccionadas quedan con su valor neutro (§4.2) y `isPartial()` devuelve `true`. Persistir un modelo parcial lanza `PartialModelException` (evita sobrescribir columnas no leídas con valores neutros). ### 6.5 `Page` ```php final readonly class Page { /** @param list $items */ public function __construct( public array $items, public int $page, // >= 1 public int $perPage, // 1..1000 public int $total, public int $totalPages, // int, siempre ) {} public function hasNext(): bool; public function hasPrev(): bool; public function toArray(): array; // items, page, per_page, total, total_pages, has_next, has_prev } ``` `perPage` fuera de rango se **corrige a los límites**, no se ignora en silencio: es una entrada de usuario y la librería debe ser tolerante en frontera y estricta en interior. `page < 1` → `1`. `toArray()` usa `snake_case` porque es el formato de **salida** (payload HTTP); las propiedades PHP usan `camelCase`. La frontera de serialización es explícita y única: `toArray()` en `Page` y en `Model`. ### 6.6 Rendimiento - Un `SELECT` por terminal. Sin N+1 en eager loading (§8.3). - Prepared statements: `Connection` mantiene un caché de `PDOStatement` por `(sql)` con límite 200 y LRU; siempre se reutiliza vía `execute(array)`. La librería **nunca** usa `bindParam`. Esto es un invariante de `Connection` y está cubierto por test. - `QueryBuilder` produce SQL idéntico entre llamadas con la misma firma (cacheable por el motor de la base y por un opcional `QueryCache` del consumidor). --- ## 7. Escritura Todas las escrituras viven en `Persistence\Persister`, invocadas desde `Repository`. `Model` no conoce la base de datos. Es deliberado (SoC): una entidad puede construirse y verificarse sin conexión. **Regla:** toda escritura recibe **un modelo** (`save`, `update`, `delete`) o **una PK + array** (`patch`, `remove`). No existe ninguna firma que acepte ambas formas. ```php // Modelo completo $repo->save($usuario); // INSERT si PK vacía, UPDATE si PK presente $repo->create(['nombre' => 'Ana']); // new + hydrate + save; devuelve el Model $repo->update($usuario); // UPDATE de todas las columnas (PK obligatoria) $repo->delete($usuario); // DELETE por PK del modelo // Por clave, sin hidratar $repo->patch(int|string $pk, array $values): bool; // UPDATE parcial $repo->remove(int|string $pk): bool; // DELETE por clave ``` | Método | Argumento | SQL | Detalle | |---|---|---|---| | `save` | `Model` | `INSERT` o `UPDATE` | Decide por PK vacía/presente. **Única** entrada de "guardar sin pensar". | | `update` | `Model` | `UPDATE ... WHERE pk = ?` | Valida; escribe **todas** las columnas escribibles (§7.1). Lanza si parcial. | | `delete` | `Model` | `DELETE ... WHERE pk = ?` | Lanza si PK vacía. | | `create` | `array $values` | `INSERT` | `new` + `hydrate($values)` + `save`. Devuelve `Model`. | | `patch` | `$pk`, `array $values` | `UPDATE SET col = ?, ...` | Solo las claves pasadas. | | `remove` | `$pk` | `DELETE WHERE pk = ?` | `true` si borró 1 fila. | `findOrCreate()` (§6.1) no está en esta tabla porque **lee primero**: es `findFirst` + `create` en una sola llamada, y su nombre lo dice. Vive en la sección de lectura por esa razón. **Por qué `save` y `update` coexisten.** `save` responde "persiste este modelo, decidas tú". `update` responde "esta fila ya existe, escribe lo que tengo". La primera es convenientemente honesta sobre su ambigüedad; la segunda es una afirmación del llamante. Ninguna sustituye a la otra, y el nombre de cada una dice cuál es. `insert` **se elimina** como método público: era `save` restringido sin aportar nada. **Por qué `patch`/`remove` y no `updateByPk`/`deleteByPk`.** El sufijo `ByPk` decía *cómo* se identifica la fila, que es ruido: toda escritura por clave lo es. `patch`/`remove` dicen *qué hacen*: modificación parcial y borrado por identidad. Además evita que `update(PK, values)` y `update(Model)` compartan nombre, que es el defecto exacto de nomenclatura que esta sección elimina. ### 7.1 Semántica de `update` `update()` escribe **todas** las columnas escribibles del modelo. No hay dirty tracking: el modelo se considera la verdad sobre la fila. Frases como "actualiza solo lo que cambió" no aplican. Para actualizaciones parciales existe `patch()`. Si el modelo proviene de `select()` parcial (`isPartial() === true`), `update()` y `save()` lanzan `PartialModelException`. Esto es la garantía de DRY aplicada al peligro real del legado: el ORM anterior no distinguía un modelo completo de uno parcial y sobreescribía la fila con valores neutros. ### 7.2 Validación `Model::validate(): array` devuelve `[propiedad => mensaje]`. Se compone en `Persistence\Validator`, con reglas **solo** las declaradas: | Regla | Disparador | Mensaje | |---|---|---| | Requerido | `#[Required]`, valor `null` o `''` | `"El campo {nombre} es requerido"` | | Enum | `#[Enum(E::class)]`, valor no instancia `E` | `"El valor de {nombre} no es válido"` | | Longitud | `#[MaxLength(n)]`, `strlen > n` | `"El campo {nombre} supera {n} caracteres"` | `isValid(): bool` = `validate() === []`. `save`/`update` llaman a `validate()` y lanzan `ValidationException` agrupando **todos** los errores (el legado concatenaba strings; aquí el mensaje es un array accesible por propiedad). **Se elimina** la validación de tipo `Text`/`BigInt`/`Json` del legado: el tipo PHP ya garantiza lo que prometía y una regla de runtime que duplica al motor de tipos es ruido. ### 7.3 Hooks Único par soportado, en `Model`, `protected`, vacíos por defecto: ```php protected function beforeInsert(): void {} protected function beforeUpdate(): void {} ``` `Persister` los invoca justo antes de construir el SQL. No hay `afterInsert`, `beforeDelete` ni observadores: para cross-cutting (auditoría, timestamps, notificaciones) existe `AuditListener` (§10.3). Un hook por fase muere en el tercer caso de uso. ### 7.4 Casting de entrada `Model::hydrate(array $data)`: - Acepta claves por **propiedad o por columna**. Si ambas existen, gana la propiedad (determinista, documentado, testeado). - Aplica el cast de §7.5. Un valor no casteable **no** se convierte en `null` silenciosamente: se lanza `InvalidArgumentException` con el nombre del campo y el valor recibido. El legado hacía `(int)` si era numérico y `null` si no, lo que producía filas con ceros que nadie escribió. - Ignora claves desconocidas (compatibilidad con payloads HTTP). - Respeta `#[Guarded]`; las guardadas **se omiten** (no se lanza) salvo `hydrate($data, strict: true)`. ### 7.5 Tabla de casting | Tipo declarado | Entrada aceptada | Resultado | |---|---|---| | `int` | `int`, `numeric string`, `bool` | `int`; resto excepción | | `float` | `float`, `numeric string`, `bool` | `float`; resto excepción | | `bool` | `bool`, `0/1`, `'0'/'1'`, `'true'/'false'` | `bool`; resto excepción | | `string` | escalar, `Stringable` | `string`; `null` si nulable | | `array` | `array`, JSON string (si `#[Ignore]`) | `array` | | `DateTimeImmutable` | `DateTimeInterface`, string ISO/`Y-m-d` | `DateTimeImmutable`; inválido excepción | | `BackedEnum` | instancia o valor del enum | instancia | | `BigDecimal` | `BigDecimal`, numérico, string numérica | `BigDecimal` | | `json` (columna JSON) | array/objeto/JSON string | array asociativo; inválido excepción | ### 7.6 Serialización y construcción `Model::toArray(?array $only = null): array` → columnas escribibles + relaciones cargadas. `DateTimeImmutable` → `DATE_ATOM`. `BigDecimal` → `string` (json_encode falla con objetos de `brick/math`; el legado los exponía como objeto, lo que truncaba la respuesta JSON). `Model::toJson(int $flags = 0): string`. **Simetría `hydrate` / `toArray`**: son la única pareja entrada/salida de datos del modelo. `fromArray`/`fromObject` **se eliminan**: son `hydrate()` con un paso previo trivial, y tener dos nombres para lo mismo es exactamente lo que esta sección elimina. ```php $modelo = new Usuario(); $modelo->hydrate($payload); // array asociativo $modelo->hydrate(get_object_vars($dto)); // objeto → array explícito en el llamante ``` `Model::refresh(Repository): static` — relee por PK y devuelve **una copia** (inmutable en la práctica; el legado mutaba la instancia y devolvía `bool`, ambigüedad innecesaria). `Model::replicate(): static` — copia con PK vacía, lista para `save`. --- ## 8. Relaciones ### 8.1 Declaración ```php use Camelia\Orm\Attribute\{TableName, PrimaryKey, AutoIncrement, Guarded}; use Camelia\Orm\Relation\{BelongsTo, HasMany, HasOne, BelongsToMany}; use Camelia\Orm\Model; #[TableName('facturaciones')] final class Facturacion extends Model { #[PrimaryKey, AutoIncrement] public ?int $codigo = null; public int $clienteCodigo = 0; // → columna cliente_codigo #[BelongsTo(Cliente::class, foreignKey: 'clienteCodigo')] public ?Cliente $cliente = null; #[HasMany(Detalle::class, foreignKey: 'facturaCodigo')] public array $detalles = []; } ``` Atributos de relación, todos `Attribute::TARGET_PROPERTY`: | Atributo | FK | Cardinalidad cargada | |---|---|---| | `#[BelongsTo(Class, foreignKey: string)]` | En la tabla **actual** | 1 modelo | | `#[HasOne(Class, foreignKey: string)]` | En la tabla **relacionada** | 1 modelo | | `#[HasMany(Class, foreignKey: string)]` | En la tabla **relacionada** | `array` de modelos | | `#[BelongsToMany(Class, through: 'pivote', foreignPivotKey: 'x', relatedPivotKey: 'y')]` | Tabla pivote explícita | `array` de modelos | **La propiedad de relación lleva el nombre del rol**, sin sufijo: `$cliente`, no `$clienteRel`. `Rel` no significaba nada y obligaba a inventar sufijos cuando coexistían FK y relación. La propiedad de FK usa el mismo sustantivo con sufijo `Codigo` (`$clienteCodigo`), que es exactamente el nombre de la columna. **`BelongsToMany` funciona** porque los metadatos de pivote son obligatorios en el atributo, no inferidos de una clave `$config['tableName']` que nunca existió. Es la corrección directa del bug #2 del legado. Clase relacionada: `class_exists()` sobre el valor recibido; si es un string no-FQCN, se resuelve bajo el namespace de la clase declarante. No existe `models\{$name}` hardcodeado: eso acoplaba el ORM a la aplicación consumidora (violación de autosuficiencia). ### 8.2 Carga explícita ```php $cliente = $factura->cliente; // null si no se cargó (no lazy) $repo->refreshRelations($factura, ['cliente']); // carga en la instancia $repo->refreshRelations($factura); // todas las declaradas ``` `refreshRelations()` reemplaza a `loadRelations()` por simetría con `Model::refresh()`: ambos refrescan estado desde la base. `load` sugería construir algo nuevo; aquí se puebla una instancia. No hay lazy loading por proxy. La propiedad empieza en `null`/`[]` y solo cambia por carga explícita o eager loading. Esto es una consecuencia directa de KISS: los proxies mágicos con `__get` son la principal fuente de bugs irrastreables de los ORM grandes. ### 8.3 Eager loading ```php $repo->find(with: ['cliente', 'cliente.ciudad']); // lista de rutas $repo->find(with: true); // todas, 1 nivel $repo->find(with: ['cliente' => ['ciudad', 'zona']]); // anidado explícito ``` Reglas: 1. **Una consulta por relación y nivel.** Sin N+1. 2. La profundidad **no** es un entero opaco: se declara en la lista de relaciones. `with: true` = todas las relaciones de primer nivel, **y solo esas**. El legado propagaba `only = []` en niveles anidados, lo que cargaba *todas* las relaciones de tercer nivel sin que el llamante lo pidiera; coste imprevisible. 3. Relación declarada inexistente → `MetadataException` (nunca se ignora). 4. Relación no cargable por falta de fila → la propiedad queda en `null`/`[]` (su valor inicial). 5. Hay un límite duro de 3 niveles; superarlo lanza `ConfigurationException` (evita el producto cartesiano accidental). Si el consumidor necesita un grafo mayor, compone llamadas a `refreshRelations()`. --- ## 9. Conexión y transacciones ```php $orm->transaction(function () use ($orm) { $orm->repository(Usuario::class)->save($u); $orm->repository(Factura::class)->save($f); }); ``` `Orm::transaction(callable): mixed` envuelve begin/commit/rollBack, **anida** con savepoints y propaga la excepción original. El legado dejaba que el caller gestionara el `PDO`: correcto en teoría, en práctica cada controlador repetía `try/catch/rollBack` con omisiones. `Connection` expone `begin()`, `commit()`, `rollBack()` y `pdo()`. El `PDO` crudo queda accesible para casos que la librería no cubre, sin que el resto del código lo use. --- ## 10. Cross-cutting opcional Todas son **interfaces** que la librería define y el consumidor implementa. La librería aporta cero implementaciones concretas salvo la indicada. ### 10.1 Logging (PSR-3) `Orm::fromArray([... 'logger' => $psrLogger])`. Se loguean: SQL lento (> `slowQueryMs`, default 500), y errores SQL antes de relanzarlos. Sin logger, no hay logs (no `error_log()` global). ### 10.2 Reloj `Support\Clock` (interface). Implementación por defecto `SystemClock`. Necesario para testear `beforeInsert` que asigna `creadoEn`. ### 10.3 Auditoría ```php interface AuditListener { /** @param array|null $before null en INSERT */ public function onWrite(string $table, string|int $pk, string $action, ?array $before, array $after): void; } ``` `Orm::fromArray(['auditListener' => new MiAuditoria()])`. Se invoca tras commit exitoso de `save`/`update`/`delete`. El valor de `$action` es uno de `'insert'`, `'update'`, `'delete'` (minúsculas, mismo vocabulario que los métodos públicos). **No** hay tabla de auditoría en la librería: la implementación la decide el consumidor (la spec de referencia asumía una clase y una tabla concretas, acoplándola al ERP). --- ## 11. Errores Todas las excepciones heredan de `Camelia\Orm\Exception\OrmException` (extends `\RuntimeException`). El sufijo `Exception` se mantiene en todos por coherencia y porque el descubrimiento por nombre es parte de la API: `catch (DuplicateKeyException)` debe leerse sin ambigüedad. ``` OrmException ├── ConfigurationException ← config/entorno inválida ├── MetadataException ← modelo mal declarado (mensaje con clase + regla M#) ├── CriteriaException ← columna desconocida / operador inválido ├── ValidationException ← validate() no vacío; errors(): array> ├── PartialModelException ← save/update sobre modelo parcial ├── RecordNotFoundException ← findByPkOrFail/firstOrFail └── DatabaseException ← envoltorio de PDOException ├── DuplicateKeyException ├── ForeignKeyViolationException └── LockTimeoutException ``` `DatabaseException::fromPdoException(PDOException $e, string $context): self` mapea por `SQLSTATE`: | SQLSTATE | Subclase | |---|---| | `23000` + errores `1062`/`1555`/`1586` | `DuplicateKeyException` | | `23000` + `1451`/`1452` | `ForeignKeyViolationException` | | `HY000` + `1205`/`1213` | `LockTimeoutException` | | otro | `DatabaseException` con `previous` | **No hay degradación.** La regla del legado ("las lecturas degradan, las escrituras fallan") se elimina: un fallo de lectura que retorna `[]` es indistinguible de "no hay filas" y convierte cualquier bug de conexión en un bug de negocio fantasma. Quien quiera degradar: ```php try { $lista = $repo->find([...]); } catch (DatabaseException) { $lista = []; } ``` y decide qué hacer, en su capa. `DatabaseException` expone `sql()`, `params()` y `context()` para logging y depuración. --- ## 12. Generación de DDL — **no implementada** > **Estado: pendiente.** Esta sección describe un componente que **no existe** en la implementación > actual. No hay `SchemaGenerator` ni `SchemaInspector`, y `#[Length]`, `#[Precision]`, `#[Unique]`, > `#[UniqueGroup]` no los lee ningún componente. `#[Index]` solo marca `PropertyMetadata::$indexed`. > > El DDL se gestiona **fuera** de la librería: la aplicación aplica su propio SQL con su herramienta > de migraciones. Cuando el generador se implemente, el contrato previsto es: ```php $ddl = (new SchemaGenerator())->createTable(Usuario::class); // CREATE TABLE `usuarios` (...) ``` Leería `ClassMetadata` + `#[Length]`/`#[Precision]`/`#[Unique]`/`#[Index]`, devolvería `string`, no ejecutaría nada y se probaría con golden files. --- ## 13. Contrato de calidad | Requisito | Umbral | |---|---| | Cobertura de líneas | ≥ 90 % (requiere `xdebug` o `pcov`) | | PHPStan | nivel 8, `phpVersion: 80200`, sin `ignoreErrors` | | Mago formatter | `mago fmt --check` limpio, `php-version = "8.2"` fijado en `mago.toml` | | Mago linter | `mago lint` sin hallazgos (umbrales de métricas y reglas desactivadas documentados en `mago.toml`) | | Mago analyzer | `mago analyze` sin hallazgos; `mago-baseline.toml` acepta solo los `mixed` de PDO | | Tests sin base de datos real | obligatorios: `Connection` se sustituye por un `FakeConnection` que registra SQL+params | | Tests con base real | integración en `tests/Integration/`, requieren `CAMELIA_TEST_DSN`; se saltan (no fallan) si no existe | | Semver | `@api` en PHPDoc para clases estables; lo no marcado puede cambiar en menor | ### 13.1 Estructura de tests ``` tests/ ├── Unit/ ← todo lo que no toca PDO │ ├── Metadata/ │ ├── Query/ ← golden SQL (assert de sql+params, no de resultado) │ ├── Persistence/ │ └── Support/ └── Integration/ ← fixtures SQL, skip si no hay DSN ``` Para SQL, la aserción es sobre `toSql()` (string + params), no sobre filas. Es la única forma de probar un compilador sin la base. Un test de integración solo verifica que el SQL compilado **ejecuta** contra MariaDB, no qué ejecuta. --- ## 14. Guía de desarrollo de la librería Uso normal: ```bash composer install composer fmt # aplica mago fmt composer fmt:check # CI: formateo limpio composer lint # CI: mago lint composer analyze # CI: mago analyze composer phpstan # CI: PHPStan nivel 8 composer test # CI: PHPUnit (unit) composer check # encadena los cinco gates, en orden composer test:integration # + MariaDB, requiere CAMELIA_TEST_DSN ``` Orden obligatorio del gate: `fmt:check` → `lint` → `analyze` → `phpstan` → `test`. Un commit a `main` requiere los cinco verdes. `composer check` los encadena; no se acepta PR con uno en rojo. ### 14.1 Nueva funcionalidad: checklist - [ ] ¿Cambia la API pública? → entrada en `CHANGELOG.md` + `@api` o no. - [ ] ¿Genera SQL? → test golden en `tests/Unit/Query/`. - [ ] ¿Lee atributos? → añadir la regla a la tabla de §5 y a `MetadataFactory`. - [ ] ¿Toca `Connection`? → mantener el invariante `execute(array)`, nunca `bindParam`. - [ ] ¿Añade un error? → subclase concreta de §11, no `OrmException` genérica. ### 14.2 Anti-patrones prohibidos (con el principio que protegen) | Anti-patrón | Principio | |---|---| | Retornar valor vacío ante excepción SQL | SoC: el ORM ejecuta; el consumidor decide | | Estado estático (singletons, caches globales fuera de `MetadataCache`) | SOLID: sustituibilidad y tests | | Puerta de entrada duplicada para la misma operación | KISS | | Helpers globales (`functions.php`) | autosuficiencia: no contaminar el consumidor | | Comportamiento distinto entre dos APIs equivalentes | DRY | | Atributos sin efecto runtime | KISS: no mentir | --- ## 15. Ejemplo integrador ```php // 1. Arranque $orm = Orm::fromEnv(); // 2. Lectura $repo = $orm->repository(Facturacion::class); $pendientes = $repo->query() ->where('estado', 'PENDIENTE') ->where('fecha', Cond::between('2024-01-01', '2024-12-31')) ->orderByDesc('fecha') ->with(['cliente.ciudad']) ->page(page: 1, perPage: 25); // 3. Escritura transaccional $orm->transaction(function () use ($orm, $pendientes) { foreach ($pendientes->items as $factura) { $factura->estado = 'PAGADA'; $orm->repository(Facturacion::class)->update($factura); } }); // 4. Serialización $json = $pendientes->items[0]->toJson(); ``` --- ## 16. Glosario de decisiones | Tema | Decisión | Alternativa descartada | |---|---|---| | Estado de entidad | Propiedades públicas + `hydrate()` | Setters mágicos, `ArrayAccess` | | Persistencia | `Repository` explícito | `$model->save()` (acopla entidad a BD) | | Guardar | `save()` para ambos casos, `update()` para afirmar existencia | `insert()`/`update()` separados y elegidos por el llamante | | Actualización parcial | `patch($pk, $values)` | `update($pk, $values)` sobrecargada | | Lectura | Prefijo `find` (`find`, `findFirst`, `findByPk`) | `findAll`/`findOne`/`find` mezclados | | Relaciones | Carga explícita / eager declarativo | Lazy por proxy (`__get`) | | Nombre de propiedad de relación | Nombre del rol (`$cliente`) | Sufijo `Rel` (`$clienteRel`) | | Errores de lectura | Lanzar | Degradar a `[]` | | Transacciones | `Orm::transaction(callable)` | Gestión manual del PDO | | Query | Inmutable | Mutable (fuga de estado entre tests) | | Auditoría | `AuditListener` opcional | Tabla hardcodeada | | Filtros | `Cond` estático | Funciones globales `_in()`, `_or()` | | Nombres de columna | `#[Column]` o `camelToSnake` | Sin convención; siempre explícito | | Interfaz vs implementación | `Connection` (rol) / `PdoConnection` (driver) | Sufijo `Interface` en todas | --- ## 17. Checklist de nomenclatura (aplicar en cada PR) Un PR que introduce un nombre nuevo debe responder: - [ ] ¿Está el término en el glosario de §0.2? Si no, ¿debería estarlo? - [ ] ¿La clase dice **qué es** y no **qué hace por dentro**? (`CriteriaCompiler` sí; `QueryHelper` no) - [ ] ¿El método sigue la regla `find*` (lectura) / verbo de destino (escritura)? - [ ] ¿El parámetro reusa un nombre canónico (`$criteria`, `$order`, `$with`, `$pk`, `$page`, `$perPage`)? - [ ] ¿`...Column()` devuelve columna y su versión sin sufijo devuelve propiedad? - [ ] ¿El booleano empieza por `is`/`has`/`can`? - [ ] ¿Introduce un sufijo de §0.3 o un nombre de §0.4? Entonces no. - [ ] Si es `@internal`, ¿está marcado en el PHPDoc?