Files
camelia-controller/docs/README.md
T
dgarcia 341d1bdc2c 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.
2026-11-15 10:14:27 -03:00

102 lines
3.4 KiB
Markdown

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