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.
This commit is contained in:
commit
341d1bdc2c
52 files changed
+7552
No files matched your search
+101
@@ -0,0 +1,101 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user