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:
commit
341d1bdc2c
52 files changed
+7552
No files matched your search
@@ -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';
|
||||
}
|
||||
}
|
||||
@@ -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';
|
||||
}
|
||||
}
|
||||
@@ -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 {}
|
||||
@@ -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()];
|
||||
}
|
||||
}
|
||||
@@ -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)];
|
||||
}
|
||||
}
|
||||
@@ -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';
|
||||
}
|
||||
}
|
||||
@@ -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';
|
||||
}
|
||||
}
|
||||
@@ -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'];
|
||||
}
|
||||
}
|
||||
@@ -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];
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user