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.
15 KiB
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, noApiOutput. - Interfaces: capacidad, sin prefijo
Ini sufijoInterface.ResourceGateway,Request. - Métodos de lectura: prefijo
find. Escrituras: verbo de destino. Unfind*nunca escribe. - Booleanos:
is/has/can.isSuccessful(),hasHeader(). - Colecciones: plural.
items,headers. - Sin abreviaturas:
Request, noReq;Response, noResp;Controller, noCtrl. - La implementación lleva el prefijo del origen:
JsonRequest; la interfaz, el rol:Request. - Claves JSON en
snake_case; código PHP encamelCase. Igual quePage::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)
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.
new JsonRequest(
method: 'GET',
path: '/articulos/7',
query: ['page' => '2'],
body: ['nombre' => 'Taladro'],
headers: ['accept' => 'application/json'],
);
query()ybody()solo leen del array inyectado; nunca de superglobales.withAttribute()devuelve copia nueva (inmutable).header()normaliza el nombre a minúsculas:Acceptyacceptson la misma cabecera.- Un
bodyno-array o un JSON inválido se rechaza en el adaptador, no aquí.
6. ResourceGateway (puerto de datos)
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/updatedevuelvennullcuando el registro no existe. ElCrudControllerlo 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.
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:
{ "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
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
$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 llamarender) ocallable(Request): Response. Route::matches(string $path): ?arraydevuelve los parámetros capturados onull.- Los parámetros se comparan como string;
{id}acepta42yabc.
11. Response
Inmutable y final readonly.
new Response(mixed $body, int $status = 200, array $headers = []);
bodyesmixed; 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
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:
{ "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
Controller::error()nunca propaga: convierte cualquierHttpErrorenResponse.- Un
Throwableque no esHttpErrorsale comoServerErrorcon mensaje genérico (no filtra detalles internos al cliente). - Todos los códigos y formas JSON de §12 son contrato público: cambiarlos es cambio de API.
- Sin estado estático mutable. Dos requests nunca comparten datos.
14. Middleware y Pipeline
interface Middleware
{
/** @param callable(Request): Response $next */
public function process(Request $request, callable $next): Response;
}
- Delega llamando
$next($request), o corta devolviendo unResponsesin llamarlo. - Forma PSR-15 sin depender de
psr/http-*: la librería sigue sin dependencias de runtime. Pipelinees 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.
$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|nullinyectado. La librería no implementa JWT ni criptografía: si devuelvenull, el token se rechaza.
16. Security\RequireRole
- Lee la identidad del atributo
userque 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 conRetry-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_ipdel request; sin él, un bucket compartidoanonymous. HaykeyResolveryclockinyectables 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
OPTIONSresponde 204 sin llegar al handler.- Origen
*+allowCredentials: truees inválido en navegadores: en ese caso se repite el origen exacto y se añadeAccess-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: Originpara 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
Throwabledel handler se registra como 500 y se relanza: el mapeo aResponselo haceRouter, no el logger. clockinyectable en milisegundos; por defectohrtime(true).
20. Middleware\ContentNegotiation
- Si el
Acceptdel cliente no casa con ninguno de los tipos aceptados → 406 con el códigonot_acceptabley una cabeceraAcceptlistando lo que sí produce. - Un
Acceptausente o vacío acepta todo (RFC 9110). - Una entrada con
q=0no cuenta como aceptada. - Añade
Content-Type: application/json; charset=utf-8si la respuesta no trae ya uno. - No comprime el cuerpo.
Responsees inmutable y el adaptador serializa; ungzencode()aquí duplicaría el trabajo y romperíaContent-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.