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:
commit
341d1bdc2c
52 files changed
+7552
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user