# camelia/controllers — Guía del programador ## Índice 1. [Instalación y arranque](#1-instalación-y-arranque) 2. [El request: nunca superglobales](#2-el-request-nunca-superglobales) 3. [La respuesta: nunca echo](#3-la-respuesta-nunca-echo) 4. [Rutas](#4-rutas) 5. [Tu primer controller](#5-tu-primer-controller) 6. [CRUD completo en una clase](#6-crud-completo-en-una-clase) 7. [El puerto ResourceGateway](#7-el-puerto-resourcegateway) 8. [Errores y códigos HTTP](#8-errores-y-códigos-http) 9. [Middlewares](#9-middlewares) 10. [Seguridad](#10-seguridad) 11. [Testing](#11-testing) 12. [Recetas frecuentes](#12-recetas-frecuentes) 13. [Trampas y errores comunes](#13-trampas-y-errores-comunes) 14. [Referencia de API](#14-referencia-de-api) --- ## 1. Instalación y arranque ```bash composer require camelia/controllers ``` El punto de entrada es un `index.php` que traduce el entorno web a un `Request`, despacha, y emite la `Response`. Esas dos traducciones son **tuyas**: la librería no toca `$_SERVER`. ```php get('/salud', static fn (): Response => new Response(['status' => 'ok'])); $request = new JsonRequest( method: $_SERVER['REQUEST_METHOD'] ?? 'GET', path: parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH) ?: '/', query: $_GET, body: json_decode(file_get_contents('php://input') ?: '{}', true) ?: [], ); $response = $router->dispatch($request); http_response_code($response->status()); foreach ($response->headers() as $name => $value) { header($name . ': ' . $value); } echo $response->toJson(); ``` > El `body` lo decodificas tú. `JsonRequest` recibe un array ya decodificado: así un JSON inválido se > rechaza donde corresponde, no dentro de la librería. --- ## 2. El request: nunca superglobales `Request` es una interfaz. Su implementación `JsonRequest` guarda arrays y es **inmutable**. ```php $request = new JsonRequest( method: 'GET', path: '/articulos', query: ['page' => '2', 'q' => 'taladro'], body: [], headers: ['authorization' => 'Bearer abc'], ); $request->method(); // 'GET' $request->path(); // '/articulos' $request->query('page'); // '2' $request->query('missing'); // null $request->query('missing', 20); // 20 $request->header('Authorization'); // 'Bearer abc' (case-insensitive) $request->attribute('id'); // null hasta que el router lo puebla ``` `withAttribute()` devuelve **copia**, no muta: ```php $a = new JsonRequest(); $b = $a->withAttribute('id', '7'); $a->attribute('id'); // null $b->attribute('id'); // '7' ``` ### Por qué no superglobales Es la única forma de testear sin servidor. Un test construye el `JsonRequest` y llama a `dispatch()`. Cero red, cero `php -S`, cero mocks del entorno. --- ## 3. La respuesta: nunca echo `Response` es inmutable y **no emite nada**. Guardarla y devolverla es todo lo que hace un handler. ```php use Camelia\Controllers\Response; new Response(['id' => 1], 201); new Response(['error' => 'x'], 404, ['X-Trace' => 'abc']); Response::noContent(); // 204, cuerpo null $r = new Response(['ok' => true]); $r->status(); // 200 $r->body(); // ['ok' => true] $r->isSuccessful(); // true $r->toJson(); // '{"ok":true}' $r->withHeader('X-Foo', 'bar'); // copia con la cabecera ``` `toJson()` aplica `JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES`. Un cuerpo `null` serializa a cadena vacía. Si el JSON no se puede codificar, lanza `JsonException` (`JSON_THROW_ON_ERROR`). --- ## 4. Rutas ```php $router = new Router(); $router->get('/articulos', $controller); $router->post('/articulos', $controller); $router->get('/articulos/{id}', $controller); $router->put('/articulos/{id}', $controller); $router->patch('/articulos/{id}', $controller); $router->delete('/articulos/{id}', $controller); $router->add('HEAD', '/articulos', $controller); // cualquier verbo ``` Los métodos son **encadenables**: cada uno devuelve el mismo router. ### Parámetros `{id}` captura un segmento (sin `/`). Se exponen como atributos del request: ```php $router->get('/facturas/{facturaId}/detalles/{detalleId}', static fn (Request $r): Response => new Response([ 'factura' => $r->attribute('facturaId'), 'detalle' => $r->attribute('detalleId'), ])); ``` ```php $router->dispatch(new JsonRequest(path: '/facturas/3/detalles/9')); // {"factura":"3","detalle":"9"} ``` Los valores son **siempre string**. Convertir a `int` es de tu handler. ### Resolución y errores | Situación | Respuesta | |---|---| | Ruta y método coinciden | El handler | | Ninguna ruta con ese path | 404 `not_found` | | El path existe pero con otro método | 405 `method_not_allowed` + `Allow` | | HEAD pedida donde hay GET | 405 con `Allow: GET, HEAD` | El 405 nunca aparece si el path no existe: solo cuando el recurso está ahí y el verbo no. ### Handlers: controller o closure ```php $router->get('/a', $controller); // llama $controller->render($request) $router->get('/b', static fn (Request $r): Response => ...); // se invoca directo ``` --- ## 5. Tu primer controller `Controller` es abstracta. Aporta helpers de respuesta; `render()` es lo único obligatorio. ```php path()) { '/salud' => $this->json(['status' => 'ok']), default => $this->error(new NotFound('Unknown health route.')), }; } } ``` ### Helpers disponibles ```php $this->json(mixed $data, int $status = 200, array $headers = []); $this->page(array $items, int $page, int $perPage, int $total); $this->created(mixed $data, string $location); // 201 + Location $this->noContent(); // 204 $this->error(HttpError $error); // status + forma JSON $this->notFound('mensaje'); // 404 ``` --- ## 6. CRUD completo en una clase `CrudController` implementa las cinco acciones REST. No tenés que escribir nada más que el nombre del recurso. ```php get('/articulos', $articulo); $router->post('/articulos', $articulo); $router->get('/articulos/{id}', $articulo); $router->put('/articulos/{id}', $articulo); $router->delete('/articulos/{id}', $articulo); ``` | Acción | Método | Ruta | Respuesta | |---|---|---|---| | `index` | GET | `/articulos` | 200 + página | | `show` | GET | `/articulos/{id}` | 200 / 404 | | `store` | POST | `/articulos` | 201 + `Location` | | `update` | PUT/PATCH | `/articulos/{id}` | 200 / 404 | | `destroy` | DELETE | `/articulos/{id}` | 204 / 404 | ### Paginación `index` lee `page` y `per_page` del query string. `page` inválido cae a 1; `per_page` se recorta a `1..1000` (default 20). ```json GET /articulos?page=2&per_page=10 { "items": [ ... ], "page": 2, "per_page": 10, "total": 43, "total_pages": 5, "has_next": true, "has_prev": true } ``` Misma forma que `Camelia\Orm\Pagination\Page::toArray()`, para que la app no traduzca nada. ### Filtros `index` reenvía `sort`, `order` y `q` al gateway como parte del `$query`: ```php $gateway->findAll(['sort' => 'nombre', 'order' => 'asc', 'q' => 'taladro', 'page' => 2, 'per_page' => 20]); ``` Filtrar por otras columnas es de tu gateway, que recibe el `$query` completo. ### Sobrescribir una acción ```php final class ArticuloController extends CrudController { public function __construct(ArticuloGateway $gateway) { parent::__construct($gateway, 'articulos'); } public function store(Request $request): Response { if (!isset($request->body()['nombre'])) { return $this->error(new ValidationFailed(['nombre' => ['Required.']])); } return parent::store($request); } } ``` --- ## 7. El puerto ResourceGateway La librería **no** conoce tu base de datos. Todo pasa por esta interfaz: ```php interface ResourceGateway { public function findAll(array $query = []): array; // list public function find(int|string $id): ?array; // null si no existe public function create(array $values): array; public function update(int|string $id, array $values): ?array; // null si no existe public function delete(int|string $id): bool; // true si borró public function count(array $query = []): ?int; // null si no sabe contar } ``` ### Contrato - Los registros son **arrays asociativos**. Serializar es del controller. - `find` y `update` devuelven `null` cuando no existe. **No lances excepciones HTTP aquí.** - `delete` devuelve `bool`. `false` → 404. - `count` puede devolver `null`; el CRUD lo interpreta como 0. ### Adaptador desde `camelia/orm` ```php final class ArticuloGateway implements ResourceGateway { public function __construct(private readonly Repository $repository) {} public function findAll(array $query = []): array { $items = $this->repository->find( order: [['nombre', 'ASC']], limit: (int) ($query['per_page'] ?? 20), offset: (((int) ($query['page'] ?? 1)) - 1) * (int) ($query['per_page'] ?? 20), ); return array_map(static fn (Articulo $a): array => $a->toArray(), $items); } public function find(int|string $id): ?array { return $this->repository->findByPk($id)?->toArray(); } public function create(array $values): array { return $this->repository->create($values)->toArray(); } public function update(int|string $id, array $values): ?array { $model = $this->repository->findByPk($id); if ($model === null) { return null; } $model->assign($values); $this->repository->save($model); return $model->toArray(); } public function delete(int|string $id): bool { return $this->repository->remove($id) > 0; } public function count(array $query = []): ?int { return $this->repository->count(); } } ``` > Este acoplamiento vive en **tu** app, no en la librería. `camelia/controllers` no declara > `camelia/orm` como dependencia. --- ## 8. Errores y códigos HTTP Toda falla es un `HttpError` con status y código estable. ```php use Camelia\Controllers\Exception\{NotFound, BadRequest, Conflict, ValidationFailed}; throw new NotFound('Articulo 7 does not exist.'); throw NotFound::resource('articulos', 7); // 'Articulos 7 does not exist.' throw NotFound::route('/nada'); // 'No route matches "/nada".' throw new ValidationFailed(['nombre' => ['Required.']]); ``` ### Forma JSON ```json { "error": { "code": "not_found", "message": "Articulo 7 does not exist." } } ``` ### Tabla completa | Clase | Status | `code` | Extra | |---|---|---|---| | `BadRequest` | 400 | `bad_request` | — | | `Unauthorized` | 401 | `unauthorized` | `WWW-Authenticate: Bearer` | | `NotFound` | 404 | `not_found` | — | | `MethodNotAllowed` | 405 | `method_not_allowed` | `Allow` | | `Conflict` | 409 | `conflict` | — | | `ValidationFailed` | 422 | `validation_failed` | `errors: {campo: [mensajes]}` | | `ServerError` | 500 | `server_error` | mensaje genérico | ### Cómo se convierten `Router::dispatch()` captura **todo**: - `HttpError` → su status y su forma. - `Throwable` cualquiera → `ServerError` (500) con mensaje genérico. **El detalle interno nunca llega al cliente.** Si un handler lanza, el cliente ve 500 limpio y vos ves la excepción en tu log. ### Códigos sin clase propia | Status | Cuándo | |---|---| | 406 `not_acceptable` | `ContentNegotiation` y el `Accept` no casa | | 429 `too_many_requests` | `RateLimit` excedido | --- ## 9. Middlewares Un middleware envuelve al handler. Delega con `$next($request)` o corta devolviendo un `Response`. ```php use Camelia\Controllers\{Middleware, Request, Response}; final readonly class Timing implements Middleware { public function process(Request $request, callable $next): Response { $start = hrtime(true); $response = $next($request); $elapsed = (hrtime(true) - $start) / 1_000_000; return $response->withHeader('X-Elapsed-Ms', (string) round($elapsed, 1)); } } ``` ### Registro ```php $router = (new Router()) ->withMiddleware(new ContentNegotiation()) ->withMiddleware(new Cors()) ->withMiddleware(new RateLimit(limit: 120)); ``` `withMiddleware()` devuelve **copia**. El router original queda intacto: ```php $public = new Router(); $private = $public->withMiddleware(new BearerAuth($verify)); $public->pipeline()->isEmpty(); // true ``` ### Orden Se ejecutan de fuera hacia dentro: el primero añadido es el más externo. ``` ContentNegotiation → Cors → RateLimit → BearerAuth → RequireRole → handler ``` Errores de orden que cuestan caro: - `Cors` **antes** de `BearerAuth`, o el preflight `OPTIONS` se come un 401. - `ContentNegotiation` **primero**, o un 406 sale sin cabeceras CORS y el navegador no lo puede leer. ### `Pipeline` directo Sin router: ```php $pipeline = new Pipeline([new Cors(), new RateLimit(limit: 10)]); $response = $pipeline->process($request, $miHandler); ``` --- ## 10. Seguridad ### `BearerAuth` ```php use Camelia\Controllers\Security\BearerAuth; $auth = new BearerAuth(static function (string $token): ?array { // Devolvé la identidad, o null si el token es inválido. return $jwt->verify($token); // ['id' => 7, 'roles' => ['admin']] }); ``` - Sin cabecera, esquema distinto o token inválido → **401**. - Éxito → la identidad queda en `$request->attribute('user')`. - La verificación del token es **tuya**. La librería no implementa JWT ni criptografía. ### `RequireRole` ```php use Camelia\Controllers\Security\RequireRole; new RequireRole(['admin', 'gerente']); // cualquiera de los dos ``` Lee roles de `$identity['roles']` (lista) o `$identity['role']` (string único). **Falla cerrado**: sin identidad, identidad no-array o roles malformados → 401. Nunca 200. ### `RateLimit` ```php new RateLimit(limit: 60, windowSeconds: 60); ``` - Excedido → **429** + `Retry-After` en segundos. - Toda respuesta lleva `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (epoch). - Clave: atributo `client_ip` del request. Sin él, un bucket compartido `anonymous`. ```php // clave personalizada new RateLimit(limit: 10, keyResolver: static fn (Request $r): string => (string) $r->attribute('user')['id'] ?? 'anon'); ``` > **El contador vive en memoria del proceso.** Detrás de N workers, el límite efectivo es N×. Es > deliberado: añadir Redis rompería la regla de cero dependencias. ### `Cors` ```php new Cors( allowedOrigins: ['https://app.midominio.com'], allowedMethods: ['GET', 'POST', 'PUT', 'DELETE'], allowedHeaders: ['Content-Type', 'Authorization'], allowCredentials: true, maxAge: 86400, ); ``` - `OPTIONS` responde **204** sin llegar al handler. - Origen no permitido → **no** se envía `Access-Control-Allow-Origin` (el navegador bloquea). - `*` + `allowCredentials: true` es inválido: se repite el origen exacto en su lugar. - Siempre envía `Vary: Origin`. ### `Logging` ```php use Camelia\Controllers\Middleware\Logging; new Logging(static function (string $level, string $message, array $context): void { error_log(sprintf('[%s] %s', $level, $message)); }); ``` Nivel según el status: `5xx` → `error`, `4xx` → `warning`, resto → `info`. Conectar un PSR-3: ```php new Logging(static fn (string $level, string $message, array $context): void => $logger->log($level, $message, $context)); ``` ### `ContentNegotiation` ```php new ContentNegotiation(); ``` - `Accept` que no casa con JSON → **406** `not_acceptable`. - `Accept` ausente → se acepta todo (RFC 9110). - `q=0` no cuenta como aceptado. - Añade `Content-Type: application/json; charset=utf-8` si falta. **No comprime.** `Response` es inmutable y el cuerpo lo serializa el adaptador; un `gzencode()` aquí duplicaría el trabajo y rompería `Content-Length`. Eso es del servidor. --- ## 11. Testing La librería está diseñada para tests sin servidor, sin base y sin red. ### Gateway en memoria ```php use Camelia\Controllers\ResourceGateway; final class ArrayGateway implements ResourceGateway { public function __construct(private array $records = []) {} public function findAll(array $query = []): array { return array_values($this->records); } public function find(int|string $id): ?array { return $this->records[$id] ?? null; } public function create(array $values): array { $id = count($this->records) + 1; $this->records[$id] = ['id' => $id] + $values; return $this->records[$id]; } public function update(int|string $id, array $values): ?array { if (!isset($this->records[$id])) { return null; } return $this->records[$id] = ['id' => $id] + $values; } public function delete(int|string $id): bool { unset($this->records[$id]); return true; } public function count(array $query = []): ?int { return count($this->records); } } ``` ### Test de un endpoint ```php use Camelia\Controllers\{JsonRequest, Router}; use PHPUnit\Framework\TestCase; final class ArticuloEndpointTest extends TestCase { public function testShowReturnsRecord(): void { $gateway = new ArrayGateway([1 => ['id' => 1, 'nombre' => 'Taladro']]); $router = new Router(); $router->get('/articulos/{id}', new ArticuloController($gateway)); $response = $router->dispatch(new JsonRequest(method: 'GET', path: '/articulos/1')); self::assertSame(200, $response->status()); self::assertSame('Taladro', $response->body()['nombre']); } } ``` ### Test de seguridad ```php public function testRejectsWithoutToken(): void { $router = (new Router())->withMiddleware( new BearerAuth(static fn (string $t): ?array => null), ); $router->get('/privado', static fn (): Response => new Response(['secret' => true])); $response = $router->dispatch(new JsonRequest(path: '/privado')); self::assertSame(401, $response->status()); self::assertStringNotContainsString('secret', $response->toJson()); } ``` ### Middleware que no toca el reloj `RateLimit` acepta `clock` para no esperar 60 segundos en un test: ```php $now = 1000; $limiter = new RateLimit(limit: 1, windowSeconds: 60, clock: fn (): int => $now); $limiter->process($request, $handler); // 200 $limiter->process($request, $handler); // 429 $now += 61; $limiter->process($request, $handler); // 200 ``` --- ## 12. Recetas frecuentes ### Ruta protegida solo para un endpoint ```php $router = new Router(); $router->get('/publico', $publico); $router->get('/privado', $privado); $router = $router->withMiddleware(new BearerAuth($verify)); ``` Un router con middleware aplica a **todas** sus rutas. Para mezclar, usá dos routers o un handler que decida. ### Respuesta sin cuerpo ```php return $this->noContent(); // 204, body null, toJson() === '' ``` ### Validación antes de escribir ```php public function store(Request $request): Response { $body = $request->body(); $errors = []; if (trim((string) ($body['nombre'] ?? '')) === '') { $errors['nombre'][] = 'Required.'; } if ($errors !== []) { return $this->error(new ValidationFailed($errors)); } return parent::store($request); } ``` ### Capturar un duplicado del ORM ```php use Camelia\Orm\Exception\DuplicateKeyException; public function store(Request $request): Response { try { return parent::store($request); } catch (DuplicateKeyException) { return $this->error(new Conflict('That record already exists.')); } } ``` ### Endpoint que no es CRUD ```php $router->post('/login', static function (Request $request): Response { $body = $request->body(); if (!isset($body['email'], $body['password'])) { return new Response(['error' => ['code' => 'bad_request', 'message' => 'Missing credentials.']], 400); } $token = Auth::attempt($body['email'], $body['password']); return $token === null ? new Response(['error' => ['code' => 'unauthorized', 'message' => 'Invalid credentials.']], 401) : new Response(['token' => $token]); }); ``` --- ## 13. Trampas y errores comunes ### `catch (HttpError)` necesita su `use` Si escribís un middleware propio con `catch (HttpError $e)`, importá `Camelia\Controllers\Exception\HttpError`. Sin el import, PHP lo resuelve a `Camelia\Controllers\HttpError` (inexistente), el catch nunca coincide y **un 404 sale como 500**. ### `render()` a mano no ve el `{id}` `CrudController` lee `$request->attribute('id')`. Solo el `Router` lo puebla. Llamar `$controller->render($request)` en un test sin `->withAttribute('id', '7')` devuelve **400**, no 200. ```php // Mal $controller->render(new JsonRequest(method: 'GET', path: '/articulos/7')); // Bien $router->dispatch(new JsonRequest(method: 'GET', path: '/articulos/7')); ``` ### El orden del pipeline importa `Cors` antes de `BearerAuth`. Si no, el preflight `OPTIONS` devuelve 401 y el navegador nunca envía la petición real. ### `RateLimit` es por proceso Detrás de 4 workers PHP-FPM, `limit: 60` significa 240 por minuto en la práctica. Si necesitás un límite real, compartí estado (Redis/APCu) en tu propia implementación de `Middleware`. ### `ContentNegotiation` no comprime No le pidas gzip. Configurá `gzip` en nginx/Apache. ### `json_encode` puede lanzar `Response::toJson()` usa `JSON_THROW_ON_ERROR`. Un cuerpo con recursos, `NAN` o UTF-8 inválido lanza `JsonException` en el `echo` del `index.php`, fuera del try del router. Sanitizá lo que devolvés. ### Los status son contrato Cambiar el 401 de `RequireRole` a 403, o el `code` de un error, rompe a los clientes que ramifican por esos valores. ### `find*` nunca escribe Si un método se llama `findAlgo`, no debe mutar nada. Es la regla de nomenclatura del ecosistema. --- ## 14. Referencia de API ### `Controller` (abstracta) | Método | Devuelve | |---|---| | `render(Request): Response` | **abstracto**, obligatorio | | `json(mixed, int = 200, array = []): Response` | `protected` | | `page(array, int, int, int): Response` | `protected` | | `created(mixed, string): Response` | `protected`, 201 + `Location` | | `noContent(): Response` | `protected`, 204 | | `error(HttpError): Response` | `protected` | | `notFound(string): Response` | `protected` | ### `CrudController` | Miembro | | |---|---| | `__construct(ResourceGateway, string $resource)` | | | `render(Request): Response` | despacha por método + `id` | | `index/show/store/update/destroy(Request): Response` | públicas, sobrescribibles | | `resourceName(): string` | | | `allowedMethods(bool $hasId): list` | | ### `Router` | Método | | |---|---| | `get/post/put/patch/delete(pattern, handler)` | encadenables | | `add(string $method, string $pattern, mixed $handler)` | | | `withMiddleware(Middleware): self` | devuelve copia | | `pipeline(): Pipeline` | | | `routes(): list` | | | `dispatch(Request): Response` | nunca lanza | ### `Route` `method()`, `pattern()`, `handler()`, `parameters(): list`, `matches(string $path): ?array`. ### `Response` `body()`, `status()`, `headers()`, `isSuccessful()`, `hasHeader(string)`, `withHeader(string, string)`, `toJson(int $flags = 0)`, `Response::noContent()`. ### `JsonRequest` `method()`, `path()`, `query(string, mixed = null)`, `body()`, `header(string)`, `attribute(string)`, `withAttribute(string, mixed)`. ### `Pipeline` `__construct(list)`, `with(Middleware): self`, `middlewares()`, `isEmpty()`, `process(Request, callable): Response`. ### Middlewares | Clase | Constructor | |---|---| | `Security\BearerAuth` | `(callable $resolver)` | | `Security\RequireRole` | `(list $roles)` | | `Security\RateLimit` | `(int $limit = 60, int $windowSeconds = 60, ?callable $clock, ?callable $keyResolver)` | | `Security\Cors` | `(list $allowedOrigins = ['*'], list $allowedMethods, list $allowedHeaders, bool $allowCredentials = false, int $maxAge = 86400)` | | `Middleware\Logging` | `(callable $sink, ?callable $clock = null)` | | `Middleware\ContentNegotiation` | `(list $acceptedTypes = ['application/json', '*/*'], bool $addContentType = true)` | ### Excepciones `BadRequest` (400) · `Unauthorized` (401) · `NotFound` (404) · `MethodNotAllowed` (405) · `Conflict` (409) · `ValidationFailed` (422) · `ServerError` (500), todas bajo `Camelia\Controllers\Exception`. --- ## Por dónde seguir - **[EJEMPLOS.md](EJEMPLOS.md)** — una API de facturación completa, ensamblada de punta a punta. - **[ARQUITECTURA.md](ARQUITECTURA.md)** — por qué cada decisión es como es. - **[especificaciones-controllers.md](especificaciones-controllers.md)** — el contrato normativo.