Files
camelia-controller/docs/especificaciones-controllers.md
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

15 KiB

Especificaciones de camelia-controllers — toolkit REST sin framework

Documento normativo y autosuficiente para construir una librería PHP 8.3+ de controllers REST. No asume ningún otro documento.

Define el contrato. Cuando una decisión tenga más de una salida razonable, se explica la elegida.


0. Nomenclatura canónica

Este glosario es normativo. Todo nombre de clase, método y parámetro proviene de esta tabla.

Regla de formación: el nombre dice qué es, no de dónde viene.

  • Clases: sustantivo singular en PascalCase. Response, no ApiOutput.
  • Interfaces: capacidad, sin prefijo I ni sufijo Interface. ResourceGateway, Request.
  • Métodos de lectura: prefijo find. Escrituras: verbo de destino. Un find* nunca escribe.
  • Booleanos: is/has/can. isSuccessful(), hasHeader().
  • Colecciones: plural. items, headers.
  • Sin abreviaturas: Request, no Req; Response, no Resp; Controller, no Ctrl.
  • La implementación lleva el prefijo del origen: JsonRequest; la interfaz, el rol: Request.
  • Claves JSON en snake_case; código PHP en camelCase. Igual que Page::toArray() del ORM.

0.1 Nombres prohibidos

BaseController · AbstractController · ApiCtrl · RouterService · HttpHelper · ResponseDto · RequestInterface (el sufijo ya está prohibido) · ControllerTrait.


1. Resumen ejecutivo

camelia-controllers construye APIs REST rápido: routing con parámetros, parsing de request, respuestas JSON y un CRUD completo sobre un puerto de datos. PHP vanilla, sin framework.

  • Paquete: camelia/controllers · namespace raíz: Camelia\Controllers
  • PHP: >=8.3 · ext-json (obligatoria)
  • Dependencias de runtime: ninguna. Ni camelia/orm (§3).
  • PSR-4: Camelia\Controllers\ → src/

Principios rectores

Principio Cómo se materializa
Nada se imprime Ninguna clase hace echo, header(), die ni exit. Siempre se devuelve Response.
Sin superglobales El request entra solo por Request. $_GET/$_POST/$_SERVER no aparecen en src/.
Independiente Los datos llegan por ResourceGateway. La app conecta el ORM con un adaptador.
Todo error es tipado Toda falla se traduce a HttpError con su status. No hay degradación silenciosa.

2. Anatomía

src/
├── Controller.php              S1-S3   base: helpers de respuesta
├── CrudController.php          S6-S9   CRUD sobre ResourceGateway
├── Router.php                  S10-S12 registro y despacho
├── Pipeline.php                S14     cadena de middlewares
├── Middleware.php              S14     interfaz PSR-15-shaped
├── Request.php                 S4      interfaz de entrada
├── JsonRequest.php             S5      implementación desde arrays
├── Response.php                S2      respuesta inmutable
├── Route.php                   S10     ruta compilada
├── ResourceGateway.php         S6      puerto de datos
├── Security/
│   ├── BearerAuth.php          S15     autenticación Bearer
│   ├── RequireRole.php         S16     autorización por rol
│   ├── RateLimit.php           S17     límite por ventana fija
│   └── Cors.php                S18     cabeceras CORS + preflight
├── Middleware/
│   ├── Logging.php             S19     una línea por request
│   └── ContentNegotiation.php  S20     acepta JSON / 406 / Content-Type
└── Exception/
    ├── ControllerException.php S13     raíz
    ├── HttpError.php           S13     error con status + forma JSON
    ├── NotFound.php            S13     404
    ├── BadRequest.php          S13     400
    ├── MethodNotAllowed.php    S13     405
    ├── ValidationFailed.php    S13     422
    ├── Conflict.php            S13     409
    ├── Unauthorized.php        S13     401
    └── ServerError.php         S13     500

3. Independencia del ORM

composer.json no requiere camelia/orm. Todo acceso a datos pasa por ResourceGateway, que la aplicación implementa (típicamente con Camelia\Orm\Repository). En src/ está prohibido importar Camelia\Orm\*.


4. Request (interfaz)

interface Request
{
    public function method(): string;          // 'GET', 'POST'… en mayúsculas
    public function path(): string;            // '/articulos/7', sin query string
    public function query(string $key, mixed $default = null): mixed;
    public function body(): array;             // cuerpo ya decodificado
    public function header(string $name): ?string;
    public function attribute(string $key): mixed;   // parámetros de ruta ya poblados
    public function withAttribute(string $key, mixed $value): static;  // copia inmutable
}

5. JsonRequest

Implementación inmutable sobre arrays. Es lo que se usa en tests y lo que un adaptador construye desde PSR-7 o superglobales.

new JsonRequest(
    method: 'GET',
    path: '/articulos/7',
    query: ['page' => '2'],
    body: ['nombre' => 'Taladro'],
    headers: ['accept' => 'application/json'],
);
  • query() y body() solo leen del array inyectado; nunca de superglobales.
  • withAttribute() devuelve copia nueva (inmutable).
  • header() normaliza el nombre a minúsculas: Accept y accept son la misma cabecera.
  • Un body no-array o un JSON inválido se rechaza en el adaptador, no aquí.

6. ResourceGateway (puerto de datos)

interface ResourceGateway
{
    /** @return list<array<string, mixed>> */
    public function findAll(array $query = []): array;

    /** @return array<string, mixed> */
    public function find(int|string $id): ?array;

    /** @return array<string, mixed> */
    public function create(array $values): array;

    /** @return array<string, mixed> */
    public function update(int|string $id, array $values): ?array;

    /** @return bool true si borró algo */
    public function delete(int|string $id): bool;

    /** @return int|null conteo total; null si el gateway no sabe contar */
    public function count(array $query = []): ?int;
}
  • Los registros se representan como arrays asociativos; serializarlos es del controller.
  • find/update devuelven null cuando el registro no existe. El CrudController lo convierte en 404; el gateway no lanza excepciones HTTP.

7. Controller

Clase abstracta base. No implementa acciones: aporta helpers de respuesta y el acceso a request.

abstract class Controller
{
    protected function json(mixed $data, int $status = 200, array $headers = []): Response;
    protected function noContent(): Response;                       // 204, sin cuerpo
    protected function created(mixed $data, string $location): Response; // 201 + Location
    protected function error(HttpError $error): Response;           // status + forma JSON
    protected function page(array $items, int $page, int $perPage, int $total): Response;
    protected function render(Request $request): Response;          // plantilla abstracta
}

render() es el único método abstracto: cada controller concreto decide su despacho.


8. CrudController extends Controller

Implementa las cinco acciones REST estándar sobre un ResourceGateway.

Acción Método Ruta Status
index GET /recurso 200 + página
show GET /recurso/{id} 200 / 404
store POST /recurso 201 + Location
update PUT/PATCH /recurso/{id} 200 / 404
destroy DELETE /recurso/{id} 204 / 404

Paginación: lee page y per_page del query string. page mínimo 1; per_page se recorta al rango 1..1000 (mismo rango que el ORM). Forma de la página:

{ "items": [], "page": 1, "per_page": 20, "total": 0, "total_pages": 0,
  "has_next": false, "has_prev": false }

El nombre del recurso para Location se resuelve con resourceName(), que cada subclase define.


9. Especialización por recurso

final class ArticuloController extends CrudController
{
    public function __construct(ArticuloGateway $gateway)
    {
        parent::__construct($gateway, 'articulos');
    }
}

render() en CrudController despacha según method + attribute('id'), así el Router solo necesita llamar render($request).


10. Route y Router

$router = new Router();
$router->get('/articulos', $controller);               // handler: objeto Controller
$router->post('/articulos', $controller);
$router->get('/articulos/{id}', $controller);

$response = $router->dispatch($request);               // Response
  • Patrón con parámetros {id}; se capturan como atributos del request (attribute('id')).
  • Ruta no encontrada → 404. Ruta encontrada con otro método → 405 con cabecera Allow.
  • Un handler puede ser Controller (se llama render) o callable(Request): Response.
  • Route::matches(string $path): ?array devuelve los parámetros capturados o null.
  • Los parámetros se comparan como string; {id} acepta 42 y abc.

11. Response

Inmutable y final readonly.

new Response(mixed $body, int $status = 200, array $headers = []);
  • body es mixed; si es array/objeto se serializa a JSON al emitir.
  • status(), headers(), body(), isSuccessful() (2xx), withHeader(string, string): self.
  • toJson(int $flags = 0): string — JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES.
  • No emite nada: una función externa hace http_response_code() y escribe el cuerpo.

12. HttpError y la jerarquía

abstract class HttpError extends ControllerException
{
    abstract public function status(): int;
    abstract public function errorCode(): string;   // 'not_found', 'validation_failed'…
    public function headers(): array;               // por defecto []
}

Forma JSON de todo error:

{ "error": { "code": "not_found", "message": "Articulo 7 does not exist." } }
Clase Status errorCode() Extra
BadRequest 400 bad_request —
Unauthorized 401 unauthorized —
NotFound 404 not_found —
MethodNotAllowed 405 method_not_allowed headers() → ['Allow' => 'GET, POST']
Conflict 409 conflict —
ValidationFailed 422 validation_failed incluye "errors": {campo: [mensajes]}
ServerError 500 server_error el mensaje se sustituye por uno genérico si se construye desde un Throwable

ValidationFailed añade errors() con la forma array<string, list<string>> que ya usa Camelia\Orm\Exception\ValidationException, para que el adaptador la mapee sin traducción.


13. Reglas de comportamiento

  1. Controller::error() nunca propaga: convierte cualquier HttpError en Response.
  2. Un Throwable que no es HttpError sale como ServerError con mensaje genérico (no filtra detalles internos al cliente).
  3. Todos los códigos y formas JSON de §12 son contrato público: cambiarlos es cambio de API.
  4. Sin estado estático mutable. Dos requests nunca comparten datos.

14. Middleware y Pipeline

interface Middleware
{
    /** @param callable(Request): Response $next */
    public function process(Request $request, callable $next): Response;
}
  • Delega llamando $next($request), o corta devolviendo un Response sin llamarlo.
  • Forma PSR-15 sin depender de psr/http-*: la librería sigue sin dependencias de runtime.
  • Pipeline es inmutable. with() devuelve copia; process() ejecuta de fuera hacia dentro (el primero añadido es el más externo). Un middleware posterior envuelve al anterior.
$router = (new Router())
    ->withMiddleware(new Cors())
    ->withMiddleware(new RateLimit(limit: 100))
    ->withMiddleware(new BearerAuth($verify))
    ->withMiddleware(new RequireRole(['admin']));

Router::withMiddleware() devuelve copia del router; el original queda intacto. El orden importa: Cors primero (responde el preflight sin autenticar), BearerAuth antes de RequireRole.


15. Security\BearerAuth

  • Lee Authorization: Bearer <token> (esquema insensible a mayúsculas).
  • Sin cabecera, esquema distinto, o token inválido → 401 + WWW-Authenticate: Bearer.
  • Con token válido adjunta la identidad en el atributo user.
  • Valida con un callable(string $token): array|null inyectado. La librería no implementa JWT ni criptografía: si devuelve null, el token se rechaza.

16. Security\RequireRole

  • Lee la identidad del atributo user que dejó BearerAuth.
  • Roles en $identity['roles'] (lista) o $identity['role'] (string único); cualquier rol de la lista configurada concede acceso.
  • Falla cerrado: sin identidad, identidad no-array, o roles malformados → 401. Nunca 200.
  • Un array de roles vacío en el constructor lanza BadRequest.

17. Security\RateLimit

  • Ventana fija por clave: cuenta y resetAt. Al pasar el límite → 429 con Retry-After.
  • Cabeceras en toda respuesta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (epoch en segundos, así lo entrega el servidor).
  • Clave por defecto: atributo client_ip del request; sin él, un bucket compartido anonymous. Hay keyResolver y clock inyectables para testear sin esperar.
  • Estado en proceso. Detrás de N workers el límite efectivo se multiplica por N. Es una limitación conocida, no un bug: la librería no depende de Redis ni APCu.

18. Security\Cors

  • OPTIONS responde 204 sin llegar al handler.
  • Origen * + allowCredentials: true es inválido en navegadores: en ese caso se repite el origen exacto y se añade Access-Control-Allow-Credentials: true.
  • Un origen no permitido no recibe Access-Control-Allow-Origin (la petición falla en el navegador, que es el comportamiento correcto).
  • Siempre envía Vary: Origin para que ningún proxy cachee la cabecera equivocada.

19. Middleware\Logging

  • Una entrada por request: método, ruta, status y duration_ms.
  • Nivel derivado del status: 5xx → error, 4xx → warning, resto → info.
  • El destino es un callable(string $level, string $message, array $context): void, no un logger PSR-3: el paquete sigue con cero dependencias. Se conecta cualquier PSR-3 con $logger->log(...).
  • Un Throwable del handler se registra como 500 y se relanza: el mapeo a Response lo hace Router, no el logger.
  • clock inyectable en milisegundos; por defecto hrtime(true).

20. Middleware\ContentNegotiation

  • Si el Accept del cliente no casa con ninguno de los tipos aceptados → 406 con el código not_acceptable y una cabecera Accept listando lo que sí produce.
  • Un Accept ausente o vacío acepta todo (RFC 9110).
  • Una entrada con q=0 no cuenta como aceptada.
  • Añade Content-Type: application/json; charset=utf-8 si la respuesta no trae ya uno.
  • No comprime el cuerpo. Response es inmutable y el adaptador serializa; un gzencode() aquí duplicaría el trabajo y rompería Content-Length. Eso es del servidor (gzip/mod_deflate).
  • Orden sugerido: el más externo del pipeline, antes de Cors, para que un 406 también lleve las cabeceras CORS y el navegador pueda leerlo.