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

+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.