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.
102 lines
3.4 KiB
Markdown
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.
|