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.
This commit is contained in:
dgarcia committed 2026-11-15 10:14:27 -03:00
commit 341d1bdc2c
52 files changed
+7552

No files matched your search

+911
View File
@@ -0,0 +1,911 @@
# 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
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use Camelia\Controllers\{JsonRequest, Router, Response};
$router = new Router();
$router->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
<?php
declare(strict_types=1);
namespace App\Http;
use Camelia\Controllers\{Controller, Request, Response};
use Camelia\Controllers\Exception\NotFound;
final class HealthController extends Controller
{
public function render(Request $request): Response
{
return match ($request->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
<?php
declare(strict_types=1);
namespace App\Http;
use Camelia\Controllers\CrudController;
final class ArticuloController extends CrudController
{
public function __construct(ArticuloGateway $gateway)
{
parent::__construct($gateway, 'articulos');
}
}
```
```php
$router->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<array>
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<string>` | |
### `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<Route>` | |
| `dispatch(Request): Response` | nunca lanza |
### `Route`
`method()`, `pattern()`, `handler()`, `parameters(): list<string>`,
`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<Middleware>)`, `with(Middleware): self`, `middlewares()`, `isEmpty()`,
`process(Request, callable): Response`.
### Middlewares
| Clase | Constructor |
|---|---|
| `Security\BearerAuth` | `(callable $resolver)` |
| `Security\RequireRole` | `(list<string> $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.