Files
dgarcia 807992ecab
Tests / PHP 8.4 (push) Failing after 1m26s
refactor!: require PHP 8.4
Drop support for PHP 8.3 and lower. The package now declares >=8.4, and CI runs
only on 8.4.

- composer.json: require php >=8.4.
- mago.toml: php-version = "8.4", matching the minimum supported version.
- phpstan.neon: phpVersion 80400.
- Upgrade phpstan/phpstan to ^2.3: 1.x cannot parse `new Foo()->bar()`, which the
  8.4 formatter now emits.
- Narrow ArrayGateway::count() to int, matching what the fixture actually returns.
- CI: single PHP 8.4 job using the php:8.4-cli container instead of setup-php,
  which failed with a TLS handshake timeout on the runner.

BREAKING CHANGE: PHP 8.4 is now required.
2026-11-15 10:58:17 -03:00

123 lines
6.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.4` | `>=8.4` |
| Parser Mago / PHPStan | 8.4 / `80400` | 8.4 / `80400` |
| `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.4`, así que toda la
sintaxis de 8.4 está disponible.
- `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.4"` en `mago.toml` debe coincidir con el mínimo declarado.** El paquete
promete `>=8.4`, así que `mago fmt` puede emitir `new X()->m()`. Si el soporte mínimo bajara,
`php-version` tendría que bajar con él: con 8.4 el formatter elimina los paréntesis de
`(new X())->m()`, sintaxis que no parsea en 8.3 ni inferiores.
- `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.