Attribute-mapped Active Record ORM for MariaDB/MySQL over PDO. - Attribute-driven metadata: TableName, PrimaryKey, AutoIncrement, Column, Guarded, Ignore, Required, Enum, Nullable, Length, Precision, Unique, UniqueGroup, Index, MaxLength. - Relationship mapping: BelongsTo, HasOne, HasMany, BelongsToMany with batched eager loading and a 3-level depth limit. - Orm entry point with fromArray, fromPdo, fromEnv and nested transactions. - Immutable Query with Cond operators and GroupCond grouping. - Repository read and write API, pagination, and typed exception hierarchy. - Declares PHP >=8.3; Mago and PHPStan pin the parser to 8.3. - MIT license.
3.7 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.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
.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.2"enmago.tomles obligatorio. Si se sube a 8.4,mago fmtreescribe(new X())->m()comonew X()->m(), que rompe el soporte declarado de 8.2.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.