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:
dgarcia committed 2026-11-15 10:14:27 -03:00
commit 341d1bdc2c
52 files changed
+7552

No files matched your search

+205
View File
@@ -0,0 +1,205 @@
# 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.