Files
camelia-controller/src/Controller.php
T
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

82 lines
2.4 KiB
PHP

<?php
declare(strict_types=1);
namespace Camelia\Controllers;
use Camelia\Controllers\Exception\HttpError;
use Camelia\Controllers\Exception\NotFound;
/**
* Base class for controllers.
*
* It provides response helpers and the request → response contract. It never writes to the output:
* a handler returns a `Response` and an adapter emits it. That is what keeps every handler testable
* without a server.
*/
abstract class Controller
{
/**
* Dispatches one request. Concrete controllers implement their own routing.
*/
abstract public function render(Request $request): Response;
/**
* @param array<string, string> $headers
*/
protected function json(mixed $data, int $status = 200, array $headers = []): Response
{
return new Response($data, $status, $headers);
}
/**
* A paginated collection in the shape shared with `Camelia\Orm\Pagination\Page`.
*
* @param list<array<string, mixed>> $items
*/
protected function page(array $items, int $page, int $perPage, int $total): Response
{
$safePage = max(1, $page);
$safePerPage = max(1, min(1000, $perPage));
$safeTotal = max(0, $total);
$totalPages = (int) ceil($safeTotal / $safePerPage);
return $this->json([
'items' => $items,
'page' => $safePage,
'per_page' => $safePerPage,
'total' => $safeTotal,
'total_pages' => $totalPages,
'has_next' => $safePage < $totalPages,
'has_prev' => $safePage > 1,
]);
}
/** 201 with a `Location` header pointing at the new resource. */
protected function created(mixed $data, string $location): Response
{
return $this->json($data, 201, ['Location' => $location]);
}
/** 204 with no body. */
protected function noContent(): Response
{
return Response::noContent();
}
/**
* Turns any error into a response. This method never throws, so an adapter can always rely on
* getting a `Response` back.
*/
protected function error(HttpError $error): Response
{
return $this->json($error->toArray(), $error->status(), $error->headers());
}
/** Convenience wrapper that keeps the error code consistent with the rest of the library. */
protected function notFound(string $message): Response
{
return $this->error(new NotFound($message));
}
}