# AGENTS.md — `camelia/controllers` Paquete `camelia/controllers`, de Dr2g Sistemas. Namespace raíz `Camelia\Controllers` → `src/` (PSR-4). Toolkit para construir APIs REST rápido: routing, parseo de request, validación y respuesta JSON. **PHP vanilla**, sin framework. ## Estado del paquete Implementado: 5 clases públicas (`Controller`, `CrudController`, `Router`, `Request`, `ResourceGateway`), 3 de soporte (`JsonRequest`, `Response`, `Route`), la cadena `Middleware`/`Pipeline`, 4 middlewares de seguridad en `src/Security/` (`BearerAuth`, `RequireRole`, `RateLimit`, `Cors`), 2 de transporte en `src/Middleware/` (`Logging`, `ContentNegotiation`), más 9 excepciones. `docs/especificaciones-controllers.md` es la spec normativa; **léela antes de tocar la API**. No inventes clases públicas sin un `S#` que las respalde. ## Documentación | Documento | Contenido | |---|---| | `docs/README.md` | Índice, requisitos, inicio en 30 s, mapa de `src/` | | `docs/GUIA-PROGRAMADOR.md` | Guía completa. **Sección 13 (trampas)** antes de escribir código | | `docs/EJEMPLOS.md` | API de facturación de punta a punta, con adaptador de ORM y tests | | `docs/ARQUITECTURA.md` | El porqué de cada decisión y la tabla de lo descartado | | `docs/especificaciones-controllers.md` | Contrato normativo: nombres, formas JSON, códigos | Al cambiar la API pública, actualiza la guía (sección 14, referencia) y la spec (§12). La tabla de «qué se descartó» de `ARQUITECTURA.md` existe para que nadie reintroduzca las decisiones ya revertidas. **No hay `src/classes/`**: los controllers viven en `src/` raíz bajo PSR-4. Si ves rutas con `classes/` en un prompt, son restos de un andamiaje vacío que se eliminó. ## Hermano con convenciones ya fijadas `../orm` (`camelia/orm`) es el paquete que fija el estilo. Su `AGENTS.md` y su `especificaciones-orm.md` son la referencia: toolchain, gate, nomenclatura y trampas son las mismas salvo lo que difiere abajo. Léelos antes de tocar el toolchain. | | aquí | en `../orm` | |---|---|---| | PHP declarado | `>=8.3` | `>=8.3` (su prosa dice 8.2: gana el composer.json) | | Parser Mago / PHPStan | 8.2 / `80300` | 8.2 / `80200` | | `mago-baseline.toml` | **no existe**, y no debe crearse | existe | ## Independencia del ORM (decisión de diseño, no descuido) `composer.json` **no** requiere `camelia/orm`. La librería define sus propios puertos (interfaces) y la app conecta el ORM por composición. Consecuencias que un agente rompería por instinto: - No importes `Camelia\Orm\*` en `src/`. Ni siquiera en docblocks, salvo como ejemplo marcado. - No envuelvas `Repository` ni `Page`. Si necesitas paginación, declara tu propio contrato; que el adaptador del ORM lo implemente es problema de la app. - Los errores de dominio llegan como excepciones propias de la librería, nunca como `Camelia\Orm\Exception\*`. El mapeo a HTTP vive dentro de este paquete. ## Nomenclatura (heredada del glosario del ORM) - Lecturas: prefijo `find`. Escrituras: verbo de destino. Un `find*` **nunca** escribe ni envía. - `...Column()` devuelve columna SQL; sin sufijo devuelve propiedad PHP. - Booleanos con `is`/`has`/`can`. Colecciones en plural. - Sin abreviaturas: `Request`, no `Req`; `Response`, no `Resp`; `Controller`, no `Ctrl`. - La implementación lleva el prefijo del origen (`JsonRequestParser`), la interfaz el rol (`RequestParser`). - Respuestas y errores en JSON con `snake_case` en las claves (igual que `Page::toArray()` del ORM: `per_page`, `total_pages`, `has_next`). El código PHP usa `camelCase`. ## Entorno local - PHP: `C:\php8.4\php.exe` (8.4.19), Composer 2.10.3. La librería declara `>=8.3`, así que **no** uses sintaxis exclusiva de 8.4; por eso `(new Foo())->bar()` conserva los paréntesis. - `declare(strict_types=1)` en todo archivo, incluidos los tests. - Sin `.env` ni servicios externos. Los tests son unitarios y puros: no levantan servidor, ni base, ni red. Un test que necesite un socket real está mal ubicado aquí. - No hay repositorio git en este directorio ni en `C:\workspaces\ws_azulerp`; no intentes `git log` para reconstruir historia. ## Gate antes de commitear ```bash composer check # fmt:check -> lint -> analyze -> phpstan -> test ``` Orden obligatorio; nunca mergees con uno en rojo. Un test individual: ```bash vendor/bin/phpunit --configuration phpunit.xml.dist --filter NombreDelTest ``` ## Trampas del toolchain - **`php-version = "8.2"` en `mago.toml` es obligatorio.** Subirlo a 8.4 hace que `mago fmt` reescriba `(new X())->m()` como `new X()->m()`, que rompe el soporte declarado y ni siquiera parsea cuando el resultado se asigna. - `mago analyze` excluye `tests/` (no carga el autoloader de Composer): reportaría `TestCase` como clase inexistente. PHPStan sí cubre los tests. - **Sin baseline.** El baseline del ORM acepta `mixed` inherente a PDO. Aquí no hay PDO como fuente de datos: un `mixed` nuevo es un error real, no un hallazgo a aceptar. Si te tienta crear `mago-baseline.toml`, primero justifícalo en la spec. - `failOnWarning`, `failOnRisky` y `failOnEmptyTestSuite` están activos: un test sin asserts o un suite vacío rompen el gate. ## Trampas de implementación (todas verificadas por los tests) - El controller **no** imprime ni hace `echo`/`header()`. Devuelve `Response`; el adaptador la emite con `http_response_code()` + `toJson()`. Un handler que escribe en el output rompe los tests. - El request entra por `Request`/`JsonRequest`, nunca por superglobales. - **`catch (HttpError)` necesita su `use`.** `Router::invoke()` resuelve `HttpError` a `Camelia\Controllers\Exception\HttpError`; sin el import, el catch nunca coincide y un 404 sale como 500. Ya pasó una vez. - `Route::compile()` escapa el literal con `preg_quote` y solo después inserta los grupos `{name}`. Invertir el orden rompe los puntos y los guiones de un path como `/archivos/reporte.json`. - `CrudController::render()` lee `attribute('id')`, que **solo** puebla el `Router`. Llamar `render()` a mano en un test sin `withAttribute('id', ...)` devuelve 400, no 200. - `CrudController::index()` reenvía `sort`, `order` y `q` al gateway como filtros; `page`/`per_page` los consume él. - `RateLimit` guarda su contador en memoria del proceso: detrás de N workers el límite efectivo es N×. Es una `shortcut:` deliberada, documentada en el código. - `Cors` va **antes** que `BearerAuth` en el pipeline: si va después, el preflight `OPTIONS` se come un 401 y el navegador nunca envía la petición real. - `RequireRole` lee el atributo `user` que pone `BearerAuth`. Usarlo sin `BearerAuth` delante da 401 siempre, por diseño (falla cerrado). - Ningún `die`/`exit`. Los códigos de status y las formas JSON de §12 son contrato público.