Files
camelia-controller/AGENTS.md
T
dgarcia 807992ecab
Tests / PHP 8.4 (push) Failing after 1m26s
refactor!: require PHP 8.4
Drop support for PHP 8.3 and lower. The package now declares >=8.4, and CI runs
only on 8.4.

- composer.json: require php >=8.4.
- mago.toml: php-version = "8.4", matching the minimum supported version.
- phpstan.neon: phpVersion 80400.
- Upgrade phpstan/phpstan to ^2.3: 1.x cannot parse `new Foo()->bar()`, which the
  8.4 formatter now emits.
- Narrow ArrayGateway::count() to int, matching what the fixture actually returns.
- CI: single PHP 8.4 job using the php:8.4-cli container instead of setup-php,
  which failed with a TLS handshake timeout on the runner.

BREAKING CHANGE: PHP 8.4 is now required.
2026-11-15 10:58:17 -03:00

6.7 KiB
Raw Blame History

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.4 >=8.4
Parser Mago / PHPStan 8.4 / 80400 8.4 / 80400
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\* en src/. Ni siquiera en docblocks, salvo como ejemplo marcado.
  • No envuelvas Repository ni Page. 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. Un find* 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, no Req; Response, no Resp; Controller, no Ctrl.
  • La implementación lleva el prefijo del origen (JsonRequestParser), la interfaz el rol (RequestParser).
  • Respuestas y errores en JSON con snake_case en las claves (igual que Page::toArray() del ORM: per_page, total_pages, has_next). El código PHP usa camelCase.

Entorno local

  • PHP: C:\php8.4\php.exe (8.4.19), Composer 2.10.3. La librería declara >=8.4, así que toda la sintaxis de 8.4 está disponible.
  • declare(strict_types=1) en todo archivo, incluidos los tests.
  • Sin .env ni 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 intentes git log para 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.4" en mago.toml debe coincidir con el mínimo declarado. El paquete promete >=8.4, así que mago fmt puede emitir new X()->m(). Si el soporte mínimo bajara, php-version tendría que bajar con él: con 8.4 el formatter elimina los paréntesis de (new X())->m(), sintaxis que no parsea en 8.3 ni inferiores.
  • mago analyze excluye tests/ (no carga el autoloader de Composer): reportaría TestCase como clase inexistente. PHPStan sí cubre los tests.
  • Sin baseline. El baseline del ORM acepta mixed inherente a PDO. Aquí no hay PDO como fuente de datos: un mixed nuevo es un error real, no un hallazgo a aceptar. Si te tienta crear mago-baseline.toml, primero justifícalo en la spec.
  • failOnWarning, failOnRisky y failOnEmptyTestSuite está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(). Devuelve Response; el adaptador la emite con http_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 su use. Router::invoke() resuelve HttpError a Camelia\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 con preg_quote y 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() lee attribute('id'), que solo puebla el Router. Llamar render() a mano en un test sin withAttribute('id', ...) devuelve 400, no 200.
  • CrudController::index() reenvía sort, order y q al gateway como filtros; page/per_page los consume él.
  • RateLimit guarda su contador en memoria del proceso: detrás de N workers el límite efectivo es N×. Es una shortcut: deliberada, documentada en el código.
  • Cors va antes que BearerAuth en el pipeline: si va después, el preflight OPTIONS se come un 401 y el navegador nunca envía la petición real.
  • RequireRole lee el atributo user que pone BearerAuth. Usarlo sin BearerAuth delante 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.