Files
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

3.4 KiB

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

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