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.
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. Unfind*nunca escribe. ...Column()devuelve columna SQL; sin sufijo devuelve propiedad PHP.- Booleanos con
is/has/can. Colecciones en plural. - Sin abreviaturas:
Metadata, noMeta;Configuration, noConfig. - 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 emitirnew Foo()->bar(). declare(strict_types=1)en todo archivo.- Sin
.envni base configurada. Los tests unitarios usanFakeConnection; la integración requiereCAMELIA_TEST_DSNy 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"enmago.tomldebe coincidir con el mínimo declarado. El paquete promete>=8.4, así quemago fmtpuede emitirnew X()->m(). Si el soporte mínimo bajara,php-versiontendrí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 analyzeexcluyetests/: no carga el autoloader de Composer, así que reportaríaPHPUnit\Framework\TestCasecomo clase inexistente. PHPStan sí cubre los tests.mago-baseline.tomlacepta los hallazgos demixedinherentes a valores que vienen de PDO. No lo regeneres a ciegas: si crece, revisa qué se aceptó.- Después de
mago fmt, correcomposer fmt:checkyphp -lsobre 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. PdoConnectionnunca usabindParam: siempreexecute(array), con statements cacheados.Queryes inmutable; cada método devuelve copia.QueryStatees el snapshot que lo permite. La única mutación esGroupConddentro dewhereGroup().Modelno importaQueryniConnection. Persistir desde el modelo rompe el contrato: usaRepository.select()parcial marcaisPartial();save()/update()sobre un modelo parcial lanzan. La vía parcial espatch($pk, $values).- Todo error SQL lanza
DatabaseException. No haytry/catchinterno que devuelva vacío. Persister,Validator,CriteriaCompiler,QueryBuilder,MetadataFactory,ConstraintyQueryStateson@internal.