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