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

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

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, 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.

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:

  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).

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 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.

// 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 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.

$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:

  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

$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 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:

$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 + @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

// 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?