Auth contract — an interface for the auth system

Intermediate5 min read·fw-09-001

Concept

Auth contract defines an interface for the authentication system. Programming to an interface allows swapping authentication backends (session, token, JWT) without changing the code that uses the auth system.

What an auth contract defines:

check(): bool — is there an authenticated user?
guest(): bool — is the request from a guest (unauthenticated)?
user(): ?UserInterface — get the authenticated user or null.
id(): int|string|null — get the authenticated user's ID.
login(UserInterface $user): void — authenticate a user for this request (and session).
logout(): void — clear authentication.
attempt(array $credentials): bool — validate credentials and authenticate if valid.

UserInterface (or Authenticatable): What the auth system needs from a user model:

getAuthIdentifier(): int|string — the user's primary key.
getAuthPassword(): string — the hashed password (for credential checking).

AuthManagerInterface: A higher-level contract for managing multiple guards. Auth::guard('api') returns a different guard than Auth::guard('web').

Guard concept: A guard defines how users are authenticated per request. The web guard uses sessions + cookies. The api guard uses tokens in headers.

Service Provider binding: $container->singleton(AuthInterface::class, SessionAuth::class) — the concrete implementation is bound in a service provider and swapped for tests.

Code Example

php

<?php
namespace Framework\Auth;

interface Authenticatable
{
    public function getAuthIdentifier(): int|string;
    public function getAuthPassword(): string;
}

interface GuardInterface
{
    public function check(): bool;
    public function guest(): bool;
    public function user(): ?Authenticatable;
    public function id(): int|string|null;
    public function login(Authenticatable $user, bool $remember = false): void;
    public function logout(): void;
    public function attempt(array $credentials): bool;
    public function validate(array $credentials): bool;
}

interface AuthManagerInterface
{
    public function guard(?string $name = null): GuardInterface;
    public function shouldUse(string $name): void;
}

// User model implements Authenticatable
class User extends \Framework\Orm\Model implements Authenticatable
{
    public function getAuthIdentifier(): int|string
    {
        return $this->id;
    }

    public function getAuthPassword(): string
    {
        return $this->password;
    }
}

// UserProvider — fetches users for the auth guard
interface UserProviderInterface
{
    public function findById(int|string $id): ?Authenticatable;
    public function findByCredentials(array $credentials): ?Authenticatable;
    public function validateCredentials(Authenticatable $user, array $credentials): bool;
}

class EloquentUserProvider implements UserProviderInterface
{
    public function __construct(private readonly string $model) {}

    public function findById(int|string $id): ?Authenticatable
    {
        return ($this->model)::find($id);
    }

    public function findByCredentials(array $credentials): ?Authenticatable
    {
        return ($this->model)::where('email', '=', $credentials['email'])->first();
    }

    public function validateCredentials(Authenticatable $user, array $credentials): bool
    {
        return password_verify($credentials['password'], $user->getAuthPassword());
    }
}

PreviousModel events — simple observer hooks on save/deleteActiveRecord ORM NextSession-based auth — login, logout, check, user()Authentication System