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:
commit
341d1bdc2c
52 files changed
+7552
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user