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.
75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
# 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`.
|