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.
10 KiB
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:
// 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:
- No se puede testear. Para verificar que un endpoint devuelve 404 hay que levantar un servidor.
- El status se decide en tres lugares.
header(),http_response_code()y el cuerpo pueden contradecirse, y nada lo detecta. $_GET,$_POST,$_SERVERaparecen 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 — uso paso a paso.
- EJEMPLOS.md — una app completa.
- especificaciones-controllers.md — el contrato normativo.