feat: initial commit of camelia/controllers
Framework-agnostic REST controller toolkit in vanilla PHP. - Router with path parameters, 404 and 405 with an Allow header. - Immutable Request, JsonRequest and Response; nothing is printed. - CrudController over a ResourceGateway port the application implements. - Composable Middleware/Pipeline chain. - Security middlewares: BearerAuth, RequireRole, RateLimit, Cors. - Transport middlewares: Logging, ContentNegotiation. - Nine typed HTTP exceptions with snake_case JSON bodies. - Declares PHP >=8.3 and no dependency on an ORM: ports are local. - MIT license.
This commit is contained in:
commit
341d1bdc2c
52 files changed
+7552
No files matched your search
@@ -0,0 +1,121 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user