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

+181
View File
@@ -0,0 +1,181 @@
<?php
declare(strict_types=1);
namespace Camelia\Controllers\Tests\Unit;
use Camelia\Controllers\CrudController;
use Camelia\Controllers\JsonRequest;
use Camelia\Controllers\Request;
use Camelia\Controllers\Response;
use Camelia\Controllers\Router;
use Camelia\Controllers\Tests\Fixture\ArrayGateway;
use PHPUnit\Framework\TestCase;
final class CrudControllerTest extends TestCase
{
private ArrayGateway $gateway;
protected function setUp(): void
{
$this->gateway = new ArrayGateway([
1 => ['id' => 1, 'nombre' => 'Taladro'],
2 => ['id' => 2, 'nombre' => 'Sierra'],
]);
}
private function controller(): CrudController
{
return new class($this->gateway) extends CrudController {
public function __construct(ArrayGateway $gateway)
{
parent::__construct($gateway, 'articulos');
}
};
}
public function testIndexReturnsPaginatedCollection(): void
{
$response = $this->controller()->render(new JsonRequest(path: '/articulos'));
self::assertSame(200, $response->status());
self::assertSame(2, $response->body()['total']);
self::assertSame(1, $response->body()['page']);
self::assertSame(20, $response->body()['per_page']);
self::assertSame(1, $response->body()['total_pages']);
self::assertFalse($response->body()['has_next']);
self::assertFalse($response->body()['has_prev']);
self::assertCount(2, $response->body()['items']);
}
public function testPerPageIsClampedToMaximum(): void
{
$response = $this->controller()->render(new JsonRequest(query: ['per_page' => '99999']));
self::assertSame(1000, $response->body()['per_page']);
}
public function testInvalidPageFallsBackToOne(): void
{
$response = $this->controller()->render(new JsonRequest(query: ['page' => 'abc']));
self::assertSame(1, $response->body()['page']);
}
public function testShowReturnsRecord(): void
{
$response = $this->controller()->render($this->withId('GET', '1'));
self::assertSame(200, $response->status());
self::assertSame('Taladro', $response->body()['nombre']);
}
public function testShowMissingRecordIs404(): void
{
$response = $this->controller()->render($this->withId('GET', '99'));
self::assertSame(404, $response->status());
self::assertSame('not_found', $response->body()['code']);
}
public function testStoreReturns201WithLocation(): void
{
$response = $this->controller()->render(new JsonRequest(
method: 'POST',
path: '/articulos',
body: ['nombre' => 'Lijadora'],
));
self::assertSame(201, $response->status());
self::assertSame('/articulos/3', $response->headers()['Location']);
self::assertSame('Lijadora', $response->body()['nombre']);
}
public function testUpdateReturnsRecord(): void
{
$response = $this->viaRouter('PUT', '/articulos/1', ['nombre' => 'Taladro Bosch']);
self::assertSame(200, $response->status());
self::assertSame('Taladro Bosch', $response->body()['nombre']);
}
public function testUpdateMissingIs404(): void
{
$response = $this->viaRouter('PATCH', '/articulos/99', ['nombre' => 'x']);
self::assertSame(404, $response->status());
}
public function testDestroyReturns204(): void
{
$response = $this->controller()->render($this->withId('DELETE', '1'));
self::assertSame(204, $response->status());
self::assertNull($response->body());
}
public function testDestroyMissingIs404(): void
{
$response = $this->controller()->render($this->withId('DELETE', '99'));
self::assertSame(404, $response->status());
}
public function testUpdateWithoutIdIs400(): void
{
$response = $this->controller()->render(new JsonRequest(method: 'PUT', path: '/articulos'));
self::assertSame(400, $response->status());
}
public function testRouterDrivesFullCrudFlow(): void
{
$router = new Router();
$controller = $this->controller();
$router->get('/articulos', $controller);
$router->post('/articulos', $controller);
$router->get('/articulos/{id}', $controller);
$router->delete('/articulos/{id}', $controller);
self::assertSame(
2,
$router->dispatch(new JsonRequest(path: '/articulos'))->body()['total'],
);
$created = $router->dispatch(new JsonRequest(method: 'POST', path: '/articulos', body: [
'nombre' => 'Martillo',
]));
self::assertSame(201, $created->status());
$deleted = $router->dispatch(new JsonRequest(method: 'DELETE', path: '/articulos/3'));
self::assertSame(204, $deleted->status());
self::assertSame(
2,
$router->dispatch(new JsonRequest(path: '/articulos'))->body()['total'],
);
}
private function withId(string $method, string $id): Request
{
return (new JsonRequest(method: $method, path: '/articulos/' . $id))->withAttribute(
'id',
$id,
);
}
/**
* Drives the request through a real router, so the `{id}` attribute is populated the same way
* production does it.
*
* @param array<string, mixed> $body
*/
private function viaRouter(string $method, string $path, array $body = []): Response
{
$router = new Router();
$controller = $this->controller();
$router->add($method, '/articulos/{id}', $controller);
return $router->dispatch(new JsonRequest(method: $method, path: $path, body: $body));
}
}