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.
Writing a Guard
Section titled “Writing a Guard”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; }}Using a Guard
Section titled “Using a Guard”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;).
Multiple Guards
Section titled “Multiple Guards”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.
Role-Based Access
Section titled “Role-Based Access”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 Are Request-Scoped
Section titled “Guards Are Request-Scoped”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.
Resolvers
Section titled “Resolvers”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.
Guards vs Resolvers
Section titled “Guards vs Resolvers”#[Guard] | #[Inject] | |
|---|---|---|
| Interface | Guard | Resolver |
| Purpose | Auth / access control | Anything |
| Throws | HttpException to reject | Up to you |
| Returns | Authenticated principal | Whatever you need |