Files
dgarcia 341d1bdc2c 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.
2026-11-15 10:14:27 -03:00

206 lines
10 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.
# Arquitectura de `camelia/controllers`
Por qué la librería es como es, y qué se descartó a propósito.
## El problema
Construir una API REST en PHP vanilla termina siempre en el mismo código, copiado endpoint por
endpoint:
```php
// el clásico
header('Content-Type: application/json');
http_response_code(200);
echo json_encode($datos);
```
Ese patrón tiene tres defectos que no se ven hasta que el proyecto crece:
1. **No se puede testear.** Para verificar que un endpoint devuelve 404 hay que levantar un servidor.
2. **El status se decide en tres lugares.** `header()`, `http_response_code()` y el cuerpo pueden
contradecirse, y nada lo detecta.
3. **`$_GET`, `$_POST`, `$_SERVER` aparecen en todas partes.** Ningún test reproduce un request sin
manipular estado global.
La librería ataca los tres: un `Request` de entrada, un `Response` de salida, y el despacho en medio.
## El flujo
```
entorno web tu app la librería
┌──────────────────────┐ ┌─────────────────────┐
│ $_SERVER, php://input│───────▶│ JsonRequest │
└──────────────────────┘ └──────────┬──────────┘
│
▼
┌────────────────────────┐
│ Router::dispatch() │
└────────────┬───────────┘
│
┌─────────────────▼──────────────────┐
│ Pipeline │
│ ContentNegotiation → Cors → │
│ RateLimit → BearerAuth → │
│ RequireRole → handler │
└─────────────────┬──────────────────┘
│
┌────────────▼───────────┐
│ Response (inmutable) │
└────────────┬───────────┘
│
┌──────────────────────┐ ┌──────────▼───────────┐
│ http_response_code, │◀───────│ tu index.php │
│ header, echo │ └──────────────────────┘
└──────────────────────┘
```
La frontera está clara: **toda** la traducción del entorno ocurre en tu `index.php`, en las dos
puntas. La librería ve solo arrays.
## Principios y cómo se materializan
| Principio | Cómo |
|---|---|
| **SoC** | Entrada (`Request`), despacho (`Router`), corte transversal (`Middleware`), salida (`Response`). Ningún componente hace dos cosas. |
| **Inmutabilidad** | `Request`, `Response`, `Route`, `Pipeline` y todos los middlewares salvo `RateLimit` son `readonly`. Una respuesta no se muta: se copia con `withHeader()`. |
| **Fail loud** | Todo error lanza y llega a `HttpError`. No hay un `catch` que devuelva `[]` o 200 vacío. |
| **Sin dependencias** | `composer.json` no declara ninguna de runtime. Ni PSR-7, ni PSR-15, ni `psr/log`. |
| **Frontera de seguridad** | El detalle interno de una excepción **nunca** llega al cliente: `ServerError` sustituye el mensaje. |
## Decisiones de diseño
### 1. `Request` es una interfaz, no un DTO
Alternativa descartada: una sola clase concreta que lea `$_SERVER` por dentro.
Se eligió la interfaz por dos razones. Primero, un adaptador PSR-7 puede implementarla sin tocar la
librería. Segundo, los tests construyen la implementación concreta con arrays literales — nada de
variables globales.
El costo es una capa extra: `Request` + `JsonRequest`. Se aceptó.
### 2. `Response` es `final readonly` con cuerpo `mixed`
Alternativa descartada: subclases `JsonResponse`, `HtmlResponse`, `EmptyResponse`.
Un solo tipo con `body: mixed` cubre todo lo que una API JSON necesita, y evita una jerarquía que
crece con cada formato. `Response::noContent()` es el atajo para el caso vacío.
`toJson()` es **explícito**: no hay `__toString()`. Serializar es una decisión, no un efecto de
concatenar.
### 3. El CRUD depende de un puerto, no del ORM
Alternativa descartada: `require camelia/orm` y usar `Repository` directo.
Era la opción más corta y se descartó a propósito. Acoplar la capa HTTP al ORM significa que la
librería de controllers no se puede usar con otro origen de datos, y que un cambio en el ORM rompe la
API. Con `ResourceGateway`, el adaptador es de la app: unas 40 líneas, una vez por recurso.
Consecuencia que suele sorprender: `find()` y `update()` devuelven `null`, **no** lanzan. El 404 lo
decide el controller. Un gateway que lanza excepciones HTTP mezclaría dos capas.
### 4. Los middlewares son una interfaz, no un trait
Alternativa descartada: `trait MiddlewareHelpers` con un método `next()`.
El trait obliga a herencia y hace imposible componer dos middlewares que ambos lo usen. La interfaz
con `callable $next` es la forma PSR-15, ya conocida, y permite closures y clases indistintamente.
`Pipeline` existe porque un `array` de middlewares no sabe ejecutarse. Encapsular la recursión en un
objeto inmutable evita el bug clásico de mutar la lista compartida entre requests.
### 5. `BearerAuth` no implementa JWT
Alternativa descartada: incluir verificación de firma con `firebase/php-jwt`.
Decidir el algoritmo, el manejo de claves y la revocación es responsabilidad de la app, no de una
librería de capa HTTP. La librería aporta lo que sí le corresponde: extraer el header, rechazar con el
status correcto y adjuntar la identidad. La verificación entra como `callable`.
Esto también mantiene la regla de cero dependencias.
### 6. `RequireRole` devuelve 401, no 403
Decisión deliberada. Un 403 confirma que el recurso existe y que el usuario está autenticado pero no
autorizado, lo cual filtra información a un atacante que enumera recursos.
Se eligió 401 por consistencia: no revelar si el recurso existe. Si tu API necesita 403 por razones
de producto (mensajes distintos en la UI), hay que cambiarlo, y es un cambio de contrato público.
### 7. `RateLimit` guarda estado en memoria
Alternativa descartada: añadir `predis/predis` o depender de APCu.
Ambas rompen «cero dependencias». La limitación (N workers → N× el límite) está documentada como
`shortcut:` en el código, con la condición de cuándo upgradear. Preferible una limitación honesta y
documentada que una dependencia escondida.
### 8. `ContentNegotiation` no comprime
Alternativa descartada: un middleware `Compression` que haga `gzencode()`.
`Response` es inmutable y el cuerpo se serializa en el adaptador. Comprimir dentro del middleware
implicaría serializar dos veces y dejar un `Content-Length` que no coincide con el cuerpo emitido — un
bug de transporte disfrazado de feature. La compresión HTTP es del servidor (`gzip`, `mod_deflate`).
Lo que sí le toca a la librería es negociar el formato, y eso es lo que hace: 406 cuando el cliente no
acepta JSON, `Content-Type` correcto en toda respuesta.
### 9. `Router::dispatch()` nunca lanza
Es deliberado que `dispatch()` capture `Throwable` y devuelva 500. Un front controller de tres líneas
no debería envolver en `try/catch`: si el dispatch lanzara, cada app tendría que repetir el mismo
manejo.
Excepción de la excepción: `Response::toJson()` puede lanzar `JsonException` si el cuerpo no es
codificable, y eso ocurre en el `echo` de tu `index.php`, fuera del `try` del router. Una respuesta
con `NAN`, un recurso o UTF-8 inválido falla ahí.
## El grafo de dependencias
```
Controller ─────────────▶ Response
│
Router ────▶ Route, Pipeline ────▶ Middleware (interfaz)
│ │
└──▶ Response Security/*, Middleware/*
│
└──▶ Request, Response, Exception/*
CrudController ────▶ Controller, ResourceGateway
```
Nada apunta hacia arriba. `ResourceGateway` y `Request` son interfaces puras: no importan nada de la
librería salvo tipos de escalares.
## Qué se descartó y no conviene reintroducir
| Descartado | Por qué |
|---|---|
| `echo` / `header()` dentro de la librería | Rompe el testeo sin servidor. |
| Superglobales en cualquier clase | Mismo motivo, y hace que dos requests compartan estado. |
| `abstract BaseController` con `index/show/store` | `CrudController` ya lo es; una segunda capa de herencia no aporta. |
| Jerarquía `JsonResponse`/`HtmlResponse` | Un tipo con `body: mixed` cubre el caso. |
| `require camelia/orm` | Acopla la capa HTTP a un origen de datos. |
| PSR-7/PSR-15 reales | Dos dependencias para reimplementar metadatos triviales. La forma se imita, no se importa. |
| `psr/log` obligatorio | Una interfaz de un método no justifica una dependencia; un `callable` basta. |
| Orden de middlewares automático | El orden tiene consecuencias reales; que lo declare quien lo entiende. |
## Verificación
| Comprobación | Comando |
|---|---|
| Tests | `composer test` |
| Análisis estático (nivel 8) | `composer phpstan` |
| Formato, lint, analyze | `composer fmt:check`, `composer lint`, `composer analyze` |
| Todo junto | `composer check` |
`composer check` exige Mago instalado y funcionando. En un entorno sin acceso al binario, PHPStan y
PHPUnit cubren la mayor parte.
## Por dónde seguir
- **[GUIA-PROGRAMADOR.md](GUIA-PROGRAMADOR.md)** — uso paso a paso.
- **[EJEMPLOS.md](EJEMPLOS.md)** — una app completa.
- **[especificaciones-controllers.md](especificaciones-controllers.md)** — el contrato normativo.