# 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) ```php 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. ```php 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) ```php interface ResourceGateway { /** @return list> */ public function findAll(array $query = []): array; /** @return array */ public function find(int|string $id): ?array; /** @return array */ public function create(array $values): array; /** @return array */ 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. ```php 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: ```json { "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 ```php 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` ```php $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`. ```php 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 ```php 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: ```json { "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>` 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` ```php 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. ```php $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 ` (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.