Tests / PHP 8.4 (push) Failing after 5m34s
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.
77 lines
3.9 KiB
Markdown
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`.
|