Files
dgarcia 341d1bdc2c 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.
2026-11-15 10:14:27 -03:00

10 KiB
Raw Permalink Blame History

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:

  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