Files
camelia-orm/AGENTS.md
T
dgarcia 0e756e45c7
Tests / PHP 8.4 (push) Failing after 5m34s
refactor!: require PHP 8.4
Drop support for PHP 8.3 and lower. The package now declares >=8.4, and CI runs
only on 8.4.

- composer.json: require php >=8.4.
- mago.toml: php-version = "8.4", matching the minimum supported version.
- phpstan.neon: phpVersion 80400.
- Upgrade phpstan/phpstan to ^2.3: 1.x cannot parse `new Foo()->bar()`, which the
  8.4 formatter now emits.
- Fix the type errors PHPStan 2 reports: class-string<static> variance,
  optional array offsets in fromEnvironment, list vs array for PdoConnection::$lru,
  ReflectionClass<Model> docblocks, Repository made covariant in T, and a redundant
  null comparison in validateRelationPath.
- CI: single PHP 8.4 job using the php:8.4-cli container instead of setup-php,
  which failed with a TLS handshake timeout on the runner.

BREAKING CHANGE: PHP 8.4 is now required.
2026-11-15 10:58:11 -03:00

77 lines
3.9 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.4`, así que toda la sintaxis de 8.4
está disponible y el formatter puede emitir `new Foo()->bar()`.
- `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.4"` en `mago.toml` debe coincidir con el mínimo declarado.** El paquete
promete `>=8.4`, así que `mago fmt` puede emitir `new X()->m()`. Si el soporte mínimo bajara,
`php-version` tendría que bajar con él: con 8.4 el formatter elimina los paréntesis de
`(new X())->m()`, sintaxis que no parsea en 8.3 ni inferiores.
- `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`.