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

+205
View File
@@ -0,0 +1,205 @@
# 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:
```php
// 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
- **[GUIA-PROGRAMADOR.md](GUIA-PROGRAMADOR.md)** — uso paso a paso.
- **[EJEMPLOS.md](EJEMPLOS.md)** — una app completa.
- **[especificaciones-controllers.md](especificaciones-controllers.md)** — el contrato normativo.
+547
View File
@@ -0,0 +1,547 @@
# Ejemplos — una API de facturación de punta a punta
Una aplicación completa y funcional: artículos, clientes y facturas, con seguridad, paginación y
tests. Todo el código es ejecutable tal cual.
## Estructura
```
app/
├── index.php punto de entrada
├── Gateway/
│ ├── ArticuloGateway.php adaptador sobre camelia/orm
│ └── ClienteGateway.php
└── Http/
├── ArticuloController.php
└── ClienteController.php
tests/
└── ApiTest.php
```
---
## 1. El punto de entrada
`app/index.php` traduce el entorno web a `Request`, despacha y emite. Es la **única** parte de la app
que toca superglobales.
```php
<?php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use App\Gateway\ArticuloGateway;
use App\Gateway\ClienteGateway;
use App\Http\ArticuloController;
use App\Http\ClienteController;
use App\Model\Articulo;
use App\Model\Cliente;
use App\Support\Jwt;
use Camelia\Controllers\Exception\Unauthorized;
use Camelia\Controllers\JsonRequest;
use Camelia\Controllers\Middleware\ContentNegotiation;
use Camelia\Controllers\Middleware\Logging;
use Camelia\Controllers\Router;
use Camelia\Controllers\Security\BearerAuth;
use Camelia\Controllers\Security\Cors;
use Camelia\Controllers\Security\RateLimit;
use Camelia\Orm\Orm;
// --- 1. Infraestructura -------------------------------------------------
$orm = Orm::fromEnvironment();
$articulos = new ArticuloController(new ArticuloGateway($orm->repository(Articulo::class)));
$clientes = new ClienteController(new ClienteGateway($orm->repository(Cliente::class)));
// --- 2. Verificación del token (decisión de la app) ----------------------
$verify = static function (string $token): ?array {
try {
return Jwt::decode($token, getenv('JWT_SECRET'));
} catch (\Throwable) {
return null;
}
};
// --- 3. Router con la cadena completa ------------------------------------
$router = (new Router())
->withMiddleware(new ContentNegotiation())
->withMiddleware(new Cors(allowedOrigins: [getenv('APP_ORIGIN') ?: '*']))
->withMiddleware(new RateLimit(limit: 120, windowSeconds: 60))
->withMiddleware(new BearerAuth($verify))
->withMiddleware(new Logging(static function (string $level, string $message, array $context): void {
error_log(sprintf('[%s] %s %s', $level, $message, json_encode($context)));
}));
$router
->get('/articulos', $articulos)
->post('/articulos', $articulos)
->get('/articulos/{id}', $articulos)
->put('/articulos/{id}', $articulos)
->delete('/articulos/{id}', $articulos)
->get('/clientes', $clientes)
->post('/clientes', $clientes)
->get('/clientes/{id}', $clientes)
->delete('/clientes/{id}', $clientes);
// --- 4. Traducción del entorno ------------------------------------------
$headers = [];
foreach ($_SERVER as $key => $value) {
// HTTP_ORIGIN => origin, HTTP_X_TRACE_ID => x-trace-id
if (str_starts_with($key, 'HTTP_')) {
$headers[strtolower(str_replace('_', '-', substr($key, 5)))] = (string) $value;
}
}
$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) ?: [],
headers: $headers,
);
// --- 5. Emisión ---------------------------------------------------------
$response = $router->dispatch($request);
http_response_code($response->status());
foreach ($response->headers() as $name => $value) {
header($name . ': ' . $value);
}
echo $response->toJson();
```
> **Por qué el `foreach` de cabeceras.** PHP entrega cada cabecera como `HTTP_<NOMBRE>` con guiones
> bajos. `JsonRequest::header()` ya compara en minúsculas, así que ese bucle es toda la normalización
> necesaria.
---
## 2. Controllers
Solo declaran el recurso. Toda la lógica REST vive en `CrudController`.
```php
<?php
declare(strict_types=1);
namespace App\Http;
use App\Gateway\ArticuloGateway;
use Camelia\Controllers\CrudController;
final class ArticuloController extends CrudController
{
public function __construct(ArticuloGateway $gateway)
{
parent::__construct($gateway, 'articulos');
}
}
```
```php
<?php
declare(strict_types=1);
namespace App\Http;
use App\Gateway\ClienteGateway;
use Camelia\Controllers\CrudController;
final class ClienteController extends CrudController
{
public function __construct(ClienteGateway $gateway)
{
parent::__construct($gateway, 'clientes');
}
}
```
---
## 3. Adaptadores de ORM
Aquí vive el acoplamiento, y solo aquí.
```php
<?php
declare(strict_types=1);
namespace App\Gateway;
use Camelia\Controllers\ResourceGateway;
use Camelia\Orm\Model;
use Camelia\Orm\Repository;
/**
* @template T of Model
*/
abstract class OrmGateway implements ResourceGateway
{
/**
* @param Repository<T> $repository
*/
public function __construct(protected readonly Repository $repository) {}
public function findAll(array $query = []): array
{
$perPage = max(1, min(1000, (int) ($query['per_page'] ?? 20)));
$page = max(1, (int) ($query['page'] ?? 1));
$items = $this->repository->find(
order: $this->orderFrom($query),
limit: $perPage,
offset: ($page - 1) * $perPage,
);
return array_map($this->toArray(...), $items);
}
public function find(int|string $id): ?array
{
$model = $this->repository->findByPk($id);
return $model === null ? null : $this->toArray($model);
}
public function create(array $values): array
{
return $this->toArray($this->repository->create($values));
}
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 $this->toArray($model);
}
public function delete(int|string $id): bool
{
return $this->repository->remove($id) > 0;
}
public function count(array $query = []): ?int
{
return $this->repository->count();
}
/** @return array<string, mixed> */
protected function toArray(Model $model): array
{
return $model->toArray();
}
/**
* Traduce `sort`/`order` del query string al formato del ORM.
*
* @param array<string, mixed> $query
* @return list<array{0: string, 1: 'ASC'|'DESC'}>
*/
private function orderFrom(array $query): array
{
$sort = (string) ($query['sort'] ?? '');
$order = strtoupper((string) ($query['order'] ?? 'ASC'));
if ($sort === '') {
return [];
}
return [[$sort, $order === 'DESC' ? 'DESC' : 'ASC']];
}
}
```
```php
<?php
declare(strict_types=1);
namespace App\Gateway;
final class ArticuloGateway extends OrmGateway {}
```
---
## 4. Manejo de duplicados
El ORM lanza `DuplicateKeyException`; la API responde 409. El mapeo vive en un controller, no en la
librería.
```php
<?php
declare(strict_types=1);
namespace App\Http;
use App\Gateway\ArticuloGateway;
use Camelia\Controllers\CrudController;
use Camelia\Controllers\Exception\Conflict;
use Camelia\Controllers\Request;
use Camelia\Controllers\Response;
use Camelia\Orm\Exception\DuplicateKeyException;
final class ArticuloController extends CrudController
{
public function __construct(ArticuloGateway $gateway)
{
parent::__construct($gateway, 'articulos');
}
public function store(Request $request): Response
{
try {
return parent::store($request);
} catch (DuplicateKeyException) {
return $this->error(new Conflict('An articulo with that code already exists.'));
}
}
}
```
---
## 5. Test de la API completa
```php
<?php
declare(strict_types=1);
namespace App\Tests;
use Camelia\Controllers\JsonRequest;
use Camelia\Controllers\ResourceGateway;
use Camelia\Controllers\Response;
use Camelia\Controllers\Router;
use Camelia\Controllers\Security\BearerAuth;
use PHPUnit\Framework\TestCase;
final class ApiTest extends TestCase
{
private function router(ResourceGateway $gateway, bool $authenticated = true): Router
{
$router = (new Router())->withMiddleware(
new BearerAuth(static fn (string $token): ?array => $authenticated ? ['id' => 1] : null),
);
$router->get('/articulos', new ArticuloController($gateway));
$router->get('/articulos/{id}', new ArticuloController($gateway));
$router->post('/articulos', new ArticuloController($gateway));
$router->delete('/articulos/{id}', new ArticuloController($gateway));
return $router;
}
public function testFullCrudFlow(): void
{
$gateway = new InMemoryGateway();
$router = $this->router($gateway);
// POST crea
$created = $router->dispatch(new JsonRequest(
method: 'POST',
path: '/articulos',
body: ['nombre' => 'Taladro', 'precio' => 120.5],
headers: ['authorization' => 'Bearer token'],
));
self::assertSame(201, $created->status());
self::assertSame('/articulos/1', $created->headers()['Location']);
self::assertSame('Taladro', $created->body()['nombre']);
// GET lo lee
$shown = $router->dispatch(new JsonRequest(
path: '/articulos/1',
headers: ['authorization' => 'Bearer token'],
));
self::assertSame(200, $shown->status());
self::assertSame(120.5, $shown->body()['precio']);
// GET lista
$listed = $router->dispatch(new JsonRequest(
path: '/articulos',
headers: ['authorization' => 'Bearer token'],
));
self::assertSame(1, $listed->body()['total']);
self::assertSame(20, $listed->body()['per_page']);
// DELETE borra
$deleted = $router->dispatch(new JsonRequest(
method: 'DELETE',
path: '/articulos/1',
headers: ['authorization' => 'Bearer token'],
));
self::assertSame(204, $deleted->status());
// Ya no existe
$missing = $router->dispatch(new JsonRequest(
path: '/articulos/1',
headers: ['authorization' => 'Bearer token'],
));
self::assertSame(404, $missing->status());
}
public function testRejectsAnonymous(): void
{
$router = $this->router(new InMemoryGateway(), authenticated: false);
$response = $router->dispatch(new JsonRequest(path: '/articulos'));
self::assertSame(401, $response->status());
self::assertSame('unauthorized', $response->body()['code']);
}
public function testPaginationClampsPerPage(): void
{
$gateway = new InMemoryGateway();
for ($i = 1; $i <= 30; ++$i) {
$gateway->create(['nombre' => 'Articulo ' . $i]);
}
$router = $this->router($gateway);
$response = $router->dispatch(new JsonRequest(
path: '/articulos',
query: ['page' => '2', 'per_page' => '10'],
headers: ['authorization' => 'Bearer token'],
));
self::assertSame(2, $response->body()['page']);
self::assertSame(10, $response->body()['per_page']);
self::assertSame(30, $response->body()['total']);
self::assertSame(3, $response->body()['total_pages']);
self::assertTrue($response->body()['has_next']);
self::assertTrue($response->body()['has_prev']);
}
}
final class InMemoryGateway implements ResourceGateway
{
/** @var array<int, array<string, mixed>> */
private array $records = [];
public function findAll(array $query = []): array
{
return array_values($this->records);
}
public function find(int|string $id): ?array
{
return $this->records[(int) $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[(int) $id])) {
return null;
}
return $this->records[(int) $id] = ['id' => (int) $id] + $values;
}
public function delete(int|string $id): bool
{
if (!isset($this->records[(int) $id])) {
return false;
}
unset($this->records[(int) $id]);
return true;
}
public function count(array $query = []): ?int
{
return count($this->records);
}
}
```
---
## 6. Recetas sueltas
### Rate limit por usuario autenticado, no por IP
```php
new RateLimit(
limit: 1000,
windowSeconds: 3600,
keyResolver: static function (Request $request): string {
$user = $request->attribute('user');
return is_array($user) ? 'user:' . (string) $user['id'] : 'anon';
},
);
```
Va **después** de `BearerAuth` en el pipeline; si va antes, todavía no hay identidad.
### CORS estricto para producción
```php
new Cors(
allowedOrigins: ['https://erp.midominio.com'],
allowedMethods: ['GET', 'POST', 'PUT', 'DELETE'],
allowedHeaders: ['Content-Type', 'Authorization'],
allowCredentials: true,
maxAge: 3600,
);
```
### Un middleware que exige un header de trazabilidad
```php
final readonly class RequireTraceId implements Middleware
{
public function process(Request $request, callable $next): Response
{
$trace = $request->header('X-Trace-Id');
if ($trace === null || $trace === '') {
return new Response(
['error' => ['code' => 'bad_request', 'message' => 'X-Trace-Id is required.']],
400,
);
}
return $next($request)->withHeader('X-Trace-Id', $trace);
}
}
```
---
## Por dónde seguir
- **[GUIA-PROGRAMADOR.md](GUIA-PROGRAMADOR.md)** — el recorrido completo, con trampas.
- **[ARQUITECTURA.md](ARQUITECTURA.md)** — el porqué de cada pieza.
+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.
+101
View File
@@ -0,0 +1,101 @@
# Documentación de `camelia/controllers`
Toolkit para construir APIs REST rápido, en PHP vanilla y sin framework.
## Índice
| Documento | Para qué sirve |
|---|---|
| [GUIA-PROGRAMADOR.md](GUIA-PROGRAMADOR.md) | Guía paso a paso: instalación, primer endpoint, CRUD, seguridad y testing. **Empieza aquí.** |
| [EJEMPLOS.md](EJEMPLOS.md) | Una API de facturación completa, con adaptador de ORM, router, seguridad y tests. |
| [ARQUITECTURA.md](ARQUITECTURA.md) | Por qué está diseñado así y qué se descartó a propósito. |
| [especificaciones-controllers.md](especificaciones-controllers.md) | Documento normativo. Define el contrato: nombres, formas JSON, códigos. |
## Qué es
Una librería que resuelve la capa HTTP de una API REST:
- **Routing** con parámetros (`/articulos/{id}`), 404 y 405 con `Allow`.
- **Request/Response** inmutables. Nada se imprime: se devuelve un objeto.
- **CRUD genérico** sobre un puerto `ResourceGateway` que la app implementa.
- **Middlewares** componibles: autenticación, roles, rate limit, CORS, logging, negociación.
## Qué NO es
- No es un framework. No trae contenedor de dependencias, ni ORM, ni plantillas.
- No lee superglobales. Todo entra por `Request`.
- No emite la respuesta. Eso lo hace tu `index.php` en cinco líneas.
- No comprime, no sirve archivos estáticos, no gestiona sesiones.
## Inicio en 30 segundos
```bash
composer require camelia/controllers
```
```php
<?php
// index.php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use Camelia\Controllers\{JsonRequest, Router, Response, Security\Cors};
$router = (new Router())->withMiddleware(new Cors());
$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,
headers: ['origin' => $_SERVER['HTTP_ORIGIN'] ?? ''],
);
$response = $router->dispatch($request);
http_response_code($response->status());
foreach ($response->headers() as $name => $value) {
header($name . ': ' . $value);
}
echo $response->toJson();
```
Un `GET /salud` devuelve `{"status":"ok"}` con status 200.
## Requisitos
| | |
|---|---|
| PHP | `>=8.3` |
| Extensiones | `ext-json` |
| Dependencias de runtime | **ninguna** |
| Testing | PHPUnit `^10.5 \|\| ^11.0` |
## Estructura del código
```
src/
├── Controller.php base con helpers de respuesta
├── CrudController.php CRUD REST sobre ResourceGateway
├── Router.php registro y despacho de rutas
├── Route.php ruta compilada
├── Pipeline.php cadena de middlewares
├── Middleware.php interfaz (forma PSR-15)
├── Request.php interfaz de entrada
├── JsonRequest.php implementación desde arrays
├── Response.php respuesta inmutable
├── ResourceGateway.php puerto de datos
├── Security/ BearerAuth, RequireRole, RateLimit, Cors
├── Middleware/ Logging, ContentNegotiation
└── Exception/ HttpError y sus 7 concreciones
```
## Convenciones que conviene saber
- **Claves JSON en `snake_case`** (`per_page`, `total_pages`); código PHP en `camelCase`.
- **Todo error lanza**; nada degrada a una respuesta vacía.
- **Los status y las formas JSON son contrato público.** Cambiarlos es cambio de API.
+398
View File
@@ -0,0 +1,398 @@
# 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<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.
```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<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`
```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 <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.