Files
camelia-controller/README.md
T
dgarcia f83d36e64f
Tests / PHP 8.4 (push) Failing after 1m37s
feat: generate OpenAPI from registered routes
2026-11-15 14:14:12 -03:00

3.0 KiB

camelia/controllers

Latest Stable Version Total Downloads License Tests

Framework-agnostic REST controller toolkit: routing, request parsing, validation and JSON responses over any data source. Vanilla PHP, no framework.

  • Package: camelia/controllers — Namespace: Camelia\Controllers
  • PHP >=8.4, extension json

What it is

The HTTP layer of a REST API, and nothing else:

  • Routing with parameters (/articulos/{id}), plus 404 and 405 responses with an Allow header.
  • Immutable request and response objects. Nothing is printed; a Response is returned and the adapter emits it.
  • Generic CRUD over a ResourceGateway port that the application implements.
  • Composable middlewares: authentication, roles, rate limiting, CORS, logging, content negotiation.

What it is not

Not a framework. No dependency-injection container, no ORM, no templating. The package declares its own ports; if an application uses an ORM, it connects it by composition.

Install

composer require camelia/controllers

OpenAPI

OpenApi::register() derives an OpenAPI 3.0 document from the routes already registered on a router and serves it under a prefix:

use Camelia\Controllers\{OpenApi, Router};

$router = new Router();
$router->get('/articulos/{id}', /* handler */);

OpenApi::register($router, '/docs/', ['title' => 'Facturación', 'version' => '2.0.0']);
  • GET /docs/ serves an HTML viewer with the document inline.
  • GET /docs/openapi.json serves the raw document.

The document describes paths, methods and path parameters. It has no request or response schemas: the library holds no payload metadata, and deriving it here would duplicate what the application already knows.

Documentation

The full developer guide, organised by task, is in docs/GUIA-PROGRAMADOR.md. The normative contract — public names, JSON shapes and status codes — is docs/especificaciones-controllers.md.

The documentation index lives in docs/README.md.

Development

composer install
composer check   # fmt:check -> lint -> analyze -> phpstan -> test

composer check must be green before anything is merged, and the steps run in that order.

The same gate runs on every commit once the hook is enabled per clone:

git config core.hooksPath .githooks

Use git commit --no-verify to bypass it for a single commit.

License

MIT. See LICENSE.