Files
camelia-orm/especificaciones-orm.md
dgarcia 66e93e3070 feat: initial commit of camelia/orm
Attribute-mapped Active Record ORM for MariaDB/MySQL over PDO.

- Attribute-driven metadata: TableName, PrimaryKey, AutoIncrement, Column,
  Guarded, Ignore, Required, Enum, Nullable, Length, Precision, Unique,
  UniqueGroup, Index, MaxLength.
- Relationship mapping: BelongsTo, HasOne, HasMany, BelongsToMany with
  batched eager loading and a 3-level depth limit.
- Orm entry point with fromArray, fromPdo, fromEnv and nested transactions.
- Immutable Query with Cond operators and GroupCond grouping.
- Repository read and write API, pagination, and typed exception hierarchy.
- Declares PHP >=8.3; Mago and PHPStan pin the parser to 8.3.
- MIT license.
2026-11-15 10:14:22 -03:00

1083 lines
49 KiB
Markdown

# 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<ModelUsuario>
$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
<?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 **verificables en runtime** (todas se validan al construir `ClassMetadata`; la violación
lanza `MetadataException::` en la primera lectura, nunca silenciosamente):
| # | Regla | Si se viola |
|---|---|---|
| M1 | La clase es `final` o no, indiferente; **debe** extenderse de `Model` | `MetadataException` en `Orm::repository()` |
| M2 | `#[TableName]` presente y no vacío | `MetadataException` |
| M3 | Exactamente **una** propiedad `#[PrimaryKey]` | `MetadataException` |
| M4 | Las propiedades mapeadas son `public` y tipadas (`ReflectionNamedType` o `?ReflectionNamedType`) | `MetadataException` |
| M5 | Una propiedad de relación es nulable (`?ModelX`) o `array` (uno a muchos) | `MetadataException` |
| M6 | La propiedad FK tiene el mismo tipo (sin nulabilidad) que la PK referida | `MetadataException` |
| M7 | No existen dos propiedades con la misma columna resultante | `MetadataException` |
**No hay fallbacks.** No existe `'SinNombre'`, no existe "si falta PK asumimos `codigo`". Un modelo
mal declarado debe fallar en la primera línea de uso, no 200 requests después.
### 4.1 Nombre de columna
Orden de resolución, sin más reglas:
1. `#[Column('nombre_col')]` explícito.
2. `camelToSnake(propertyName)`: inserta `_` antes de cada mayúscula interna
(`codigoEmpresa` → `codigo_empresa`, `idZona` → `id_zona`, `normal` → `normal`).
La conversión es pura y vive en `Support\NameConverter::camelToSnake()`, con tests unitarios.
Caracteres no ASCII se prohíben en columnas (`MetadataException`): MariaDB los admite, la
legibilidad no.
### 4.2 Valores iniciales
`Model::__construct()` asigna a cada propiedad pública **sin valor por defecto declarado** el valor
neutro del tipo. `initializeProperties()` **no existe** como API pública; es responsabilidad del
constructor.
| Tipo | Inicial |
|---|---|
| `?X` | `null` |
| `string` | `''` |
| `int`, `float`, `BigDecimal` | `0`, `0.0`, `BigDecimal::of('0')` |
| `bool` | `false` |
| `array` | `[]` |
| `DateTimeImmutable` | `new DateTimeImmutable('now')` |
| otro no soportado | `null` |
Los valores declarados explícitamente (`public bool $activo = true;`) **nunca** se sobreescriben.
> **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<string, PropertyMetadata> 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<PropertyMetadata> */
public function relations(): array;
/** @return list<PropertyMetadata> */
public function indexed(): array;
/** @return list<string> 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<string, mixed|Cond> $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)` | `(<sql>)` — **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<string>
$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<scalar>` |
| `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<Model> $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<string,mixed>|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<string,list<string>>
├── 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?