Files
camelia-orm/AGENTS.md
T
dgarcia 66e93e3070 feat: initial commit of camelia/orm
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.
2026-11-15 10:14:22 -03:00

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. 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.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 .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.2" en mago.toml es obligatorio. Si se sube a 8.4, mago fmt reescribe (new X())->m() como new X()->m(), que rompe el soporte declarado de 8.2.
  • 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.