Files
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

3.9 KiB

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

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.