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.
This commit is contained in:
dgarcia committed 2026-11-15 10:14:22 -03:00
commit 66e93e3070
97 files changed
+12188

No files matched your search

+74
View File
@@ -0,0 +1,74 @@
# AGENTS.md — `camelia/orm` (librería PHP independiente)
Paquete `camelia/orm`, de Dr2g Sistemas. Namespace raíz `Camelia\Orm` → `src/` (PSR-4).
## Leer primero
`especificaciones-orm.md` es la fuente de verdad del diseño. **La §0 es normativa de
nomenclatura**: todo nombre de clase, método y parámetro sale de su glosario. Si un nombre no está
ahí, no existe. Ojo: la spec conserva el nombre histórico `azulerp/orm` y `Azul\Orm` en algunos
ejemplos; el nombre vigente es `camelia/orm` y `Camelia\Orm`.
## Reglas de nomenclatura que más se rompen
- Lecturas: prefijo `find`. Escrituras: verbo de destino. Un `find*` **nunca** escribe.
- `...Column()` devuelve columna SQL; sin sufijo devuelve propiedad PHP.
- Booleanos con `is`/`has`/`can`. Colecciones en plural.
- Sin abreviaturas: `Metadata`, no `Meta`; `Configuration`, no `Config`.
- La implementación lleva el prefijo del driver (`PdoConnection`), la interfaz el rol (`Connection`).
## No arrastres el legado
Descartado a propósito: `SimpleModelBase`, `Conexion`, `_in()`, `FilterExpr`, `$clienteRel`,
`findOne`, `findAll`, `findOrFail`, `FluentQuery`, `updateByPk`, `deleteByPk`, `loadRelations`,
`Model::fill`, `fromArray`/`fromObject`, `SqlDialect`, `CriterionCompiler`, `ConnectionInterface`.
Si tu memoria sugiere alguno de esos nombres, está obsoleta.
## Entorno local
- PHP: `C:\php8.4\php.exe` (8.4.19). La librería declara `>=8.2`, así que **no** uses sintaxis de
8.3/8.4 (y por eso `(new Foo())->bar()` conserva los paréntesis).
- `declare(strict_types=1)` en todo archivo.
- Sin `.env` ni base configurada. Los tests unitarios usan `FakeConnection`; la integración
requiere `CAMELIA_TEST_DSN` y se **salta** si falta.
## Gate antes de commitear
```bash
composer check # fmt:check -> lint -> analyze -> phpstan -> test
```
Nunca mergees con uno en rojo. Orden obligatorio.
## Toolchain: Mago
`mago.toml` configura formatter, linter y analyzer. Notas que ahorran tiempo:
- **`php-version = "8.2"` en `mago.toml` es obligatorio.** Si se sube a 8.4, `mago fmt` reescribe
`(new X())->m()` como `new X()->m()`, que rompe el soporte declarado de 8.2.
- `mago analyze` excluye `tests/`: no carga el autoloader de Composer, así que reportaría
`PHPUnit\Framework\TestCase` como clase inexistente. PHPStan sí cubre los tests.
- `mago-baseline.toml` acepta los hallazgos de `mixed` inherentes a valores que vienen de PDO.
No lo regeneres a ciegas: si crece, revisa qué se aceptó.
- Después de `mago fmt`, corre `composer fmt:check` y `php -l` sobre lo tocado. El formatter es
estable, pero el error de versión anterior producía PHP que solo parseaba en 8.4.
## Base de datos de referencia
No hay base conectada. El esquema accesible vía MCP `mariadb` es `aguaflow_prod` (tablas en
snake_case: `usuarios`, `facturaciones`, `clientes`, `zonas`, `auditoria`). Úsalo solo para observar
patrones reales de nombres y tipos; **no** como DSN de tests.
## Trampas de implementación
- El compilador SQL se prueba con `toSql()` (golden SQL + params), nunca con resultados de filas.
- `PdoConnection` **nunca** usa `bindParam`: siempre `execute(array)`, con statements cacheados.
- `Query` es inmutable; cada método devuelve copia. `QueryState` es el snapshot que lo permite. La
única mutación es `GroupCond` dentro de `whereGroup()`.
- `Model` no importa `Query` ni `Connection`. Persistir desde el modelo rompe el contrato: usa
`Repository`.
- `select()` parcial marca `isPartial()`; `save()`/`update()` sobre un modelo parcial lanzan. La vía
parcial es `patch($pk, $values)`.
- Todo error SQL lanza `DatabaseException`. No hay `try/catch` interno que devuelva vacío.
- `Persister`, `Validator`, `CriteriaCompiler`, `QueryBuilder`, `MetadataFactory`, `Constraint` y
`QueryState` son `@internal`.