Skip to content
Antares

Controllers

Controllers are plain PHP classes. You define routes by placing attributes on methods — no base class, no interface required.

use Antares\Router\Attributes\Get;
class UserController
{
#[Get('/users')]
public function index(): array
{
return ['users' => []];
}
}

Register the controller in your RouteServiceProvider:

$router->register(UserController::class);

That’s all. The router scans the class via reflection and picks up every annotated method.


Segments wrapped in {} are extracted and injected by name. The value is cast to whatever type you declare:

#[Get('/users/{id}')]
public function show(int $id): array
{
return ['id' => $id];
}

Supported types: int, float, bool, string. A value that doesn’t fit the type (/users/abc for int $id) is rejected with 400 Bad Request.


Any scalar parameter that isn’t a route segment is resolved from the query string:

#[Get('/users')]
public function index(int $page = 1, int $perPage = 15): array
{
return ['page' => $page, 'perPage' => $perPage];
}

GET /users?page=2&perPage=50 injects $page = 2 and $perPage = 50.

  • Only int, float, bool and string parameters are read from the query string, cast the same way as route parameters. Invalid values are rejected with 400, and so are array values such as ?page[]=1 (Query parameter page must be a single value.).
  • If the query parameter is missing, the default value is used. Always give query parameters a default: a missing parameter without one fails with 500 (Cannot resolve parameter $page in controller., visible with APP_DEBUG on), even when the parameter is nullable.

Type-hint a #[Dto] class to have the request body decoded, hydrated, and validated automatically. If the body is missing fields or has values of the wrong type, a 400 response is returned; if it breaks a validation rule, a 422. Either way your method is never called:

#[Post('/users', 201)]
public function store(CreateUserRequest $request): UserResponse
{
return new UserResponse(id: 1, name: $request->name);
}

See DTOs for how to define request DTOs.


Type-hint ServerRequestInterface to get the raw PSR-7 request:

use Psr\Http\Message\ServerRequestInterface;
#[Get('/debug')]
public function debug(ServerRequestInterface $request): array
{
return ['method' => $request->getMethod()];
}

Type-hint UploadedFileInterface and name the parameter to match the form field. If the request has no file field with that name, or several files under that name (avatar[]), it is rejected with 400. Add #[File] to check size, MIME type and extension:

use Antares\Validation\Attributes\File;
use Psr\Http\Message\UploadedFileInterface;
#[Post('/avatars', 201)]
public function upload(
#[File(maxSize: 2048, mimes: ['image/png', 'image/jpeg'])] UploadedFileInterface $avatar,
): array
{
$avatar->moveTo('/storage/avatars/' . uniqid() . '.jpg');
return ['uploaded' => true];
}

The return value of your method determines the response:

Return typeResult
arrayJSON response with the route’s status code
#[ResponseDto] objectSerialized to JSON via the Serializer
ResponseInterfaceReturned as-is (headers from ResponseBag are still added)
null / voidEmpty body with the route’s status code
A scalar (string, int, …)JSON-encoded, e.g. "ok"
Any other objectError: 500, Controller returned an object without #[ResponseDto]

JSON responses get Content-Type: application/json.

#[Get('/ping')]
public function ping(): array
{
return ['pong' => true];
}
#[Get('/users/{id}')]
public function show(int $id): UserResponse
{
return new UserResponse(id: $id, name: 'John');
}

See Response DTOs for how to define and shape serialized responses.

#[Delete('/users/{id}', 204)]
public function destroy(int $id): void
{
// 204 No Content
}
use Nyholm\Psr7\Response;
#[Get('/health')]
public function health(): Response
{
return new Response(200, [], 'OK');
}

Controllers are built by the container, so constructor dependencies are autowired. Method parameters work too: any class type that isn’t a #[Dto], a PSR request or file, or a parameter with #[Guard] / #[Inject] is resolved from the container.

class PostController
{
public function __construct(
private readonly PostRepository $posts,
) {}
#[Get('/posts')]
public function index(): array
{
return $this->posts->all();
}
}

The container autowires PostRepository and any of its own dependencies automatically.