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.
206 lines
10 KiB
Markdown
206 lines
10 KiB
Markdown
# 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.
|