Skip to content
Antares

Guards & Resolvers

A guard authenticates an incoming request and returns a typed value — usually the authenticated user or tenant — which is then injected directly into your controller method. If the guard throws, the request is rejected before anything else runs.

A resolver extracts and shapes request data into a typed value — query params, headers, or anything that isn’t about authentication.


A guard implements Antares\Http\ResolverInterfaces\Guard. It is built by the container on every request, so it can have constructor dependencies:

use Antares\Http\ResolverInterfaces\Guard;
use Antares\Exceptions\HttpException;
use Psr\Http\Message\ServerRequestInterface;
final class JwtGuard implements Guard
{
public function __construct(
private readonly JwtService $jwt,
) {}
public function resolve(ServerRequestInterface $request): AuthUser
{
$header = $request->getHeaderLine('Authorization');
$token = preg_replace('/^Bearer\s+/i', '', $header);
$user = $this->jwt->decode($token);
if ($user === null) {
throw new HttpException(401, 'Unauthorized');
}
return $user;
}
}

Apply #[Guard(GuardClass::class)] to the parameter that should receive the resolved value:

use Antares\Http\Attributes\Guard;
class PostController
{
#[Post('/posts', 201)]
public function store(
#[Guard(JwtGuard::class)] AuthUser $user,
CreatePostRequest $request,
): PostResponse {
return new PostResponse(
id: 1,
title: $request->title,
authorId: $user->id,
);
}
}

Parameters are resolved in the order they are declared. Put guard parameters first: then, if the guard throws, the request body is never hydrated and the controller method is never called.

The attribute class Antares\Http\Attributes\Guard and the interface Antares\Http\ResolverInterfaces\Guard share a short name. If you need both in one file, alias one of them (use Antares\Http\ResolverInterfaces\Guard as GuardContract;).


Different routes can use different guards. You can also stack multiple guards on a single method:

class ReportController
{
#[Get('/reports')]
public function index(
#[Guard(TenantGuard::class)] Tenant $tenant,
#[Guard(JwtGuard::class)] AuthUser $user,
): array {
return ['tenant' => $tenant->id, 'user' => $user->id];
}
}

Guards run in the order they appear in the parameter list, each as a separate call: two parameters with the same guard run it twice.


Guards are a natural place to enforce roles. Throw an HttpException with 403 if the resolved user does not have the required access:

final class AdminGuard implements Guard
{
public function __construct(
private readonly JwtService $jwt,
) {}
public function resolve(ServerRequestInterface $request): AuthUser
{
$user = $this->jwt->decode(
preg_replace('/^Bearer\s+/i', '', $request->getHeaderLine('Authorization'))
);
if ($user === null) {
throw new HttpException(401, 'Unauthorized');
}
if (!$user->isAdmin()) {
throw new HttpException(403, 'Forbidden');
}
return $user;
}
}
#[Delete('/users/{id}', 204)]
public function destroy(
#[Guard(AdminGuard::class)] AuthUser $user,
int $id,
): void {
// only admins reach here
}

Guards always receive the ServerRequestInterface and are designed to authenticate based on request data — headers, cookies, tokens. If you need logic that has nothing to do with the current request, that belongs in a plain service resolved by the container, not a guard.


A resolver extracts and shapes request data into a typed value — query params, headers, or anything that isn’t about authentication. Unlike guards, resolvers never throw auth errors; they just parse and return.

use Antares\Http\ResolverInterfaces\Resolver;
use Psr\Http\Message\ServerRequestInterface;
final class PaginationResolver implements Resolver
{
public function resolve(ServerRequestInterface $request): Pagination
{
$params = $request->getQueryParams();
return new Pagination(
page: (int) ($params['page'] ?? 1),
perPage: (int) ($params['per_page'] ?? 15),
);
}
}

Apply #[Inject(ResolverClass::class)] to the parameter:

use Antares\Http\Attributes\Inject;
class PostController
{
#[Get('/posts')]
public function index(
#[Guard(JwtGuard::class)] AuthUser $user,
#[Inject(PaginationResolver::class)] Pagination $page,
): array {
...
}
}

Resolvers can have constructor dependencies — the container autowires them just like guards.


#[Guard]#[Inject]
InterfaceGuardResolver
PurposeAuth / access controlAnything
ThrowsHttpException to rejectUp to you
ReturnsAuthenticated principalWhatever you need