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.
49 KiB
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, noBaseBean.Page, noPaginadorResultado. - Interfaces: capacidad, sin prefijo
Ini sufijoInterfacecuando el sustantivo ya es un rol.Clock,Dialect,Listener. La excepción esConnection(§0.3): ver la nota. - Métodos de lectura/escritura: verbo en infinitivo o 3ª persona, nunca gerundio.
find, nofinding. Las consultas usan el prefijofind; las escrituras usan el verbo SQL directo. - Colecciones: plural.
items, noitemList.properties(), nogetPropertyArr(). - 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, noConfig;Metadata, noMeta;Repository, noRepo. 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/mathessuggest. - 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/) yPSR-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:
- Se elimina la duplicación
SimpleModelBase↔SimpleModelBaseQueries. Una sola clase,Camelia\Orm\Model, delegando enRepository(composición, no herencia de implementaciones). - Se eliminan los helpers globales
_in(),_or(), etc. Colisionan con el consumidor y violan autosuficiencia. Se reemplazan por una clase estáticaCondcon métodos encadenables. manyToManyfunciona o no existe. La spec de referencia lo documentaba roto. Aquí es un contrato real con tabla pivote declarativa.- 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. - Coherencia de tipos en la salida.
Page::$totalPagesesintsiempre. - Se elimina
#[Timestamp],#[OnInsert],#[OnUpdate],#[Description],#[Comment],#[Check]. Eran declarativos sin efecto en runtime; su lugar está en elCREATE TABLEde 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.
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
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:
#[Column('nombre_col')]explícito.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:
DateTimese reemplaza porDateTimeImmutablecomo tipo mapeado. Mutar unDateTimeinsidetoArray()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).
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).
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.
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
$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
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
SELECTpor terminal. Sin N+1 en eager loading (§8.3). - Prepared statements:
Connectionmantiene un caché dePDOStatementpor(sql)con límite 200 y LRU; siempre se reutiliza víaexecute(array). La librería nunca usabindParam. Esto es un invariante deConnectiony está cubierto por test. QueryBuilderproduce SQL idéntico entre llamadas con la misma firma (cacheable por el motor de la base y por un opcionalQueryCachedel 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.
// 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:
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
nullsilenciosamente: se lanzaInvalidArgumentExceptioncon el nombre del campo y el valor recibido. El legado hacía(int)si era numérico ynullsi 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) salvohydrate($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.
$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
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
$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
$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:
- Una consulta por relación y nivel. Sin N+1.
- 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 propagabaonly = []en niveles anidados, lo que cargaba todas las relaciones de tercer nivel sin que el llamante lo pidiera; coste imprevisible. - Relación declarada inexistente →
MetadataException(nunca se ignora). - Relación no cargable por falta de fila → la propiedad queda en
null/[](su valor inicial). - 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
$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
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:
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
SchemaGeneratorniSchemaInspector, y#[Length],#[Precision],#[Unique],#[UniqueGroup]no los lee ningún componente.#[Index]solo marcaPropertyMetadata::$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:
$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:
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+@apio 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 invarianteexecute(array), nuncabindParam. - ¿Añade un error? → subclase concreta de §11, no
OrmExceptiongené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
// 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? (
CriteriaCompilersí;QueryHelperno) - ¿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?