# 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.