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.
This commit is contained in:
commit
66e93e3070
97 files changed
+12188
No files matched your search
@@ -0,0 +1,74 @@
|
||||
# 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
|
||||
|
||||
```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.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`.
|
||||
Reference in new issue
Block a user