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.
1083 lines
49 KiB
Markdown
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?
|