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.
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 | Guía paso a paso: instalación, primer endpoint, CRUD, seguridad y testing. Empieza aquí. |
| EJEMPLOS.md | Una API de facturación completa, con adaptador de ORM, router, seguridad y tests. |
| ARQUITECTURA.md | Por qué está diseñado así y qué se descartó a propósito. |
| 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 conAllow. - Request/Response inmutables. Nada se imprime: se devuelve un objeto.
- CRUD genérico sobre un puerto
ResourceGatewayque 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.phpen cinco líneas. - No comprime, no sirve archivos estáticos, no gestiona sesiones.
Inicio en 30 segundos
composer require camelia/controllers
<?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 encamelCase. - 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.