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.
399 lines
15 KiB
Markdown
399 lines
15 KiB
Markdown
# 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.
|