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.
6.7 KiB
AGENTS.md — camelia/controllers
Paquete camelia/controllers, de Dr2g Sistemas. Namespace raíz Camelia\Controllers → src/
(PSR-4). Toolkit para construir APIs REST rápido: routing, parseo de request, validación y respuesta
JSON. PHP vanilla, sin framework.
Estado del paquete
Implementado: 5 clases públicas (Controller, CrudController, Router, Request, ResourceGateway),
3 de soporte (JsonRequest, Response, Route), la cadena Middleware/Pipeline, 4 middlewares
de seguridad en src/Security/ (BearerAuth, RequireRole, RateLimit, Cors), 2 de transporte en
src/Middleware/ (Logging, ContentNegotiation), más 9 excepciones.
docs/especificaciones-controllers.md es la spec normativa; léela antes de tocar la API. No
inventes clases públicas sin un S# que las respalde.
Documentación
| Documento | Contenido |
|---|---|
docs/README.md |
Índice, requisitos, inicio en 30 s, mapa de src/ |
docs/GUIA-PROGRAMADOR.md |
Guía completa. Sección 13 (trampas) antes de escribir código |
docs/EJEMPLOS.md |
API de facturación de punta a punta, con adaptador de ORM y tests |
docs/ARQUITECTURA.md |
El porqué de cada decisión y la tabla de lo descartado |
docs/especificaciones-controllers.md |
Contrato normativo: nombres, formas JSON, códigos |
Al cambiar la API pública, actualiza la guía (sección 14, referencia) y la spec (§12). La tabla de
«qué se descartó» de ARQUITECTURA.md existe para que nadie reintroduzca las decisiones ya revertidas.
No hay src/classes/: los controllers viven en src/ raíz bajo PSR-4. Si ves rutas con
classes/ en un prompt, son restos de un andamiaje vacío que se eliminó.
Hermano con convenciones ya fijadas
../orm (camelia/orm) es el paquete que fija el estilo. Su AGENTS.md y su
especificaciones-orm.md son la referencia: toolchain, gate, nomenclatura y trampas son las mismas
salvo lo que difiere abajo. Léelos antes de tocar el toolchain.
| aquí | en ../orm |
|
|---|---|---|
| PHP declarado | >=8.3 |
>=8.3 (su prosa dice 8.2: gana el composer.json) |
| Parser Mago / PHPStan | 8.2 / 80300 |
8.2 / 80200 |
mago-baseline.toml |
no existe, y no debe crearse | existe |
Independencia del ORM (decisión de diseño, no descuido)
composer.json no requiere camelia/orm. La librería define sus propios puertos (interfaces) y
la app conecta el ORM por composición. Consecuencias que un agente rompería por instinto:
- No importes
Camelia\Orm\*ensrc/. Ni siquiera en docblocks, salvo como ejemplo marcado. - No envuelvas
RepositoryniPage. Si necesitas paginación, declara tu propio contrato; que el adaptador del ORM lo implemente es problema de la app. - Los errores de dominio llegan como excepciones propias de la librería, nunca como
Camelia\Orm\Exception\*. El mapeo a HTTP vive dentro de este paquete.
Nomenclatura (heredada del glosario del ORM)
- Lecturas: prefijo
find. Escrituras: verbo de destino. Unfind*nunca escribe ni envía. ...Column()devuelve columna SQL; sin sufijo devuelve propiedad PHP.- Booleanos con
is/has/can. Colecciones en plural. - Sin abreviaturas:
Request, noReq;Response, noResp;Controller, noCtrl. - La implementación lleva el prefijo del origen (
JsonRequestParser), la interfaz el rol (RequestParser). - Respuestas y errores en JSON con
snake_caseen las claves (igual quePage::toArray()del ORM:per_page,total_pages,has_next). El código PHP usacamelCase.
Entorno local
- PHP:
C:\php8.4\php.exe(8.4.19), Composer 2.10.3. La librería declara>=8.3, así que no uses sintaxis exclusiva de 8.4; por eso(new Foo())->bar()conserva los paréntesis. declare(strict_types=1)en todo archivo, incluidos los tests.- Sin
.envni servicios externos. Los tests son unitarios y puros: no levantan servidor, ni base, ni red. Un test que necesite un socket real está mal ubicado aquí. - No hay repositorio git en este directorio ni en
C:\workspaces\ws_azulerp; no intentesgit logpara reconstruir historia.
Gate antes de commitear
composer check # fmt:check -> lint -> analyze -> phpstan -> test
Orden obligatorio; nunca mergees con uno en rojo. Un test individual:
vendor/bin/phpunit --configuration phpunit.xml.dist --filter NombreDelTest
Trampas del toolchain
php-version = "8.2"enmago.tomles obligatorio. Subirlo a 8.4 hace quemago fmtreescriba(new X())->m()comonew X()->m(), que rompe el soporte declarado y ni siquiera parsea cuando el resultado se asigna.mago analyzeexcluyetests/(no carga el autoloader de Composer): reportaríaTestCasecomo clase inexistente. PHPStan sí cubre los tests.- Sin baseline. El baseline del ORM acepta
mixedinherente a PDO. Aquí no hay PDO como fuente de datos: unmixednuevo es un error real, no un hallazgo a aceptar. Si te tienta crearmago-baseline.toml, primero justifícalo en la spec. failOnWarning,failOnRiskyyfailOnEmptyTestSuiteestán activos: un test sin asserts o un suite vacío rompen el gate.
Trampas de implementación (todas verificadas por los tests)
- El controller no imprime ni hace
echo/header(). DevuelveResponse; el adaptador la emite conhttp_response_code()+toJson(). Un handler que escribe en el output rompe los tests. - El request entra por
Request/JsonRequest, nunca por superglobales. catch (HttpError)necesita suuse.Router::invoke()resuelveHttpErroraCamelia\Controllers\Exception\HttpError; sin el import, el catch nunca coincide y un 404 sale como 500. Ya pasó una vez.Route::compile()escapa el literal conpreg_quotey solo después inserta los grupos{name}. Invertir el orden rompe los puntos y los guiones de un path como/archivos/reporte.json.CrudController::render()leeattribute('id'), que solo puebla elRouter. Llamarrender()a mano en un test sinwithAttribute('id', ...)devuelve 400, no 200.CrudController::index()reenvíasort,orderyqal gateway como filtros;page/per_pagelos consume él.RateLimitguarda su contador en memoria del proceso: detrás de N workers el límite efectivo es N×. Es unashortcut:deliberada, documentada en el código.Corsva antes queBearerAuthen el pipeline: si va después, el preflightOPTIONSse come un 401 y el navegador nunca envía la petición real.RequireRolelee el atributouserque poneBearerAuth. Usarlo sinBearerAuthdelante da 401 siempre, por diseño (falla cerrado).- Ningún
die/exit. Los códigos de status y las formas JSON de §12 son contrato público.