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.
82 lines
2.4 KiB
PHP
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));
|
|
}
|
|
}
|