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.
This commit is contained in:
dgarcia committed 2026-11-15 10:14:27 -03:00
commit 341d1bdc2c
52 files changed
+7552

No files matched your search

+26
View File
@@ -0,0 +1,26 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Exception;
/**
* The request was malformed or carried invalid values.
*/
final class BadRequest extends HttpError
{
public function __construct(string $message = 'The request is malformed.')
{
parent::__construct($message);
}
public function status(): int
{
return 400;
}
public function errorCode(): string
{
return 'bad_request';
}
}
+26
View File
@@ -0,0 +1,26 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Exception;
/**
* The request conflicts with current state, such as a duplicate key.
*/
final class Conflict extends HttpError
{
public function __construct(string $message = 'The request conflicts with the current state.')
{
parent::__construct($message);
}
public function status(): int
{
return 409;
}
public function errorCode(): string
{
return 'conflict';
}
}
+10
View File
@@ -0,0 +1,10 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Exception;
/**
* Base type of every exception raised by the library.
*/
class ControllerException extends \RuntimeException {}
+30
View File
@@ -0,0 +1,30 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Exception;
/**
* A failure with an HTTP status and a stable machine-readable code.
*
* The status and code are public contract: clients branch on them.
*/
abstract class HttpError extends ControllerException
{
abstract public function status(): int;
/** Stable snake_case identifier sent to the client, such as `not_found`. */
abstract public function errorCode(): string;
/** @return array<string, string> */
public function headers(): array
{
return [];
}
/** @return array<string, mixed> */
public function toArray(): array
{
return ['code' => $this->errorCode(), 'message' => $this->getMessage()];
}
}
+43
View File
@@ -0,0 +1,43 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Exception;
/**
* The path exists but does not accept this verb. The `Allow` header lists the accepted ones.
*/
final class MethodNotAllowed extends HttpError
{
/** @param list<string> $allowed */
public function __construct(
private readonly array $allowed,
) {
parent::__construct(sprintf('Method not allowed. Accepted methods: %s.', implode(
', ',
$allowed,
)));
}
/** @return list<string> */
public function allowed(): array
{
return $this->allowed;
}
public function status(): int
{
return 405;
}
public function errorCode(): string
{
return 'method_not_allowed';
}
/** @return array<string, string> */
public function headers(): array
{
return ['Allow' => implode(', ', $this->allowed)];
}
}
+36
View File
@@ -0,0 +1,36 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Exception;
/**
* The requested resource does not exist.
*/
final class NotFound extends HttpError
{
public function __construct(string $message = 'The requested resource does not exist.')
{
parent::__construct($message);
}
public static function resource(string $name, int|string $id): self
{
return new self(sprintf('%s %s does not exist.', ucfirst($name), (string) $id));
}
public static function route(string $path): self
{
return new self(sprintf('No route matches "%s".', $path));
}
public function status(): int
{
return 404;
}
public function errorCode(): string
{
return 'not_found';
}
}
+34
View File
@@ -0,0 +1,34 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Exception;
/**
* An unexpected failure. When built from a throwable the client only sees a generic message, so
* internal details never leak into a response.
*/
final class ServerError extends HttpError
{
public function __construct(
string $message = 'An unexpected error occurred.',
?\Throwable $previous = null,
) {
parent::__construct($message, 0, $previous);
}
public static function fromThrowable(\Throwable $throwable): self
{
return new self('An unexpected error occurred.', $throwable);
}
public function status(): int
{
return 500;
}
public function errorCode(): string
{
return 'server_error';
}
}
+32
View File
@@ -0,0 +1,32 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Exception;
/**
* The request carries no valid authentication.
*/
final class Unauthorized extends HttpError
{
public function __construct(string $message = 'Authentication is required.')
{
parent::__construct($message);
}
public function status(): int
{
return 401;
}
public function errorCode(): string
{
return 'unauthorized';
}
/** @return array<string, string> */
public function headers(): array
{
return ['WWW-Authenticate' => 'Bearer'];
}
}
+44
View File
@@ -0,0 +1,44 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Exception;
/**
* Input failed validation. Errors are grouped by field.
*
* The shape matches `Camelia\Orm\Exception\ValidationException::errors()`, so an adapter can forward
* the ORM's errors without reshaping them.
*/
final class ValidationFailed extends HttpError
{
/** @param array<string, list<string>> $errors */
public function __construct(
private readonly array $errors,
string $message = 'The submitted data is invalid.',
) {
parent::__construct($message);
}
/** @return array<string, list<string>> */
public function errors(): array
{
return $this->errors;
}
public function status(): int
{
return 422;
}
public function errorCode(): string
{
return 'validation_failed';
}
/** @return array<string, mixed> */
public function toArray(): array
{
return parent::toArray() + ['errors' => $this->errors];
}
}