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