ez-php / auth

2.4.2 2026-09-16 14:31 UTC

Requires

• php: ^8.5
• ez-php/cache: ^2.0
• ez-php/console: ^2.0
• ez-php/contracts: ^2.0
• ez-php/http: ^2.0
• ez-php/rate-limiter: ^2.0

Requires (Dev)

• ez-php/docker: ^2.0
• ez-php/testing-application: ^2.0
• friendsofphp/php-cs-fixer: ^3.94
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^13.0

MIT

• Andreas Uretschnig

• framework
• php
• Authentication
• auth
• ez-php

Published on Packagist.org on 2026-09-16 14:34 UTC

README

Authentication module for the ez-php framework — session, Bearer token, JWT, and personal access token authentication with a flexible user provider interface.

Requirements

• PHP 8.5+
• ez-php/framework 0.*

Installation

composer require ez-php/auth

Setup

Register the service provider in your application:

$app->register(\EzPhp\Auth\AuthServiceProvider::class);

// Optional — register JWT support:
$app->register(\EzPhp\Auth\JwtServiceProvider::class);

Implement UserProviderInterface to connect your user storage:

use EzPhp\Auth\UserProviderInterface;

class UserProvider implements UserProviderInterface
{
    public function findById(int|string $id): ?UserInterface { ... }
    public function findByToken(string $token): ?UserInterface { ... }
}

Bind it before AuthServiceProvider:

$this->app->bind(UserProviderInterface::class, UserProvider::class);

Usage

Session / Bearer token authentication

use EzPhp\Auth\Auth;

// Authenticate
Auth::login($user);
$user = Auth::user();
Auth::logout();

// Protect routes with middleware
$router->get('/dashboard', $handler)->middleware(\EzPhp\Auth\Middleware\AuthMiddleware::class);

JWT authentication

JWT_SECRET=your-secret-key
JWT_TTL=3600

$jwt = $app->make(\EzPhp\Auth\Jwt\JwtManager::class);

$token    = $jwt->issue($user->getAuthId());
$claims   = $jwt->validate($token);

// Protect routes
$router->get('/api/me', $handler)->middleware(\EzPhp\Auth\Middleware\JwtMiddleware::class);

Rate-limited login attempts

Login-attempt throttling is not part of this module (see "What Does NOT Belong Here") — compose ez-php/rate-limiter's ThrottleMiddleware in front of your login route instead. Since ThrottleMiddleware needs route-specific constructor arguments (limiter, attempt count, window, key), bind a small dedicated subclass so the container can autowire it like any other middleware class-string:

use EzPhp\RateLimiter\Middleware\ThrottleMiddleware;
use EzPhp\RateLimiter\RateLimiterInterface;

final class LoginThrottleMiddleware extends ThrottleMiddleware
{
    public function __construct(RateLimiterInterface $limiter)
    {
        // 5 attempts per 10 minutes, keyed 'rate_limit:login:<ip>' — independent
        // of any other ThrottleMiddleware instance guarding other routes.
        parent::__construct($limiter, maxAttempts: 5, decaySeconds: 600, keyPrefix: 'rate_limit:login');
    }
}

$router->post('/login', $handler)
    ->middleware(LoginThrottleMiddleware::class) // runs first — throttled requests never reach AuthMiddleware
    ->middleware(AuthMiddleware::class);

Auth's static-façade design is untouched by this — the throttle lives entirely in the middleware chain in front of it.

Personal access tokens

$manager = $app->make(\EzPhp\Auth\PersonalAccessTokenManager::class);

[$rawToken, $token] = $manager->create($userId, 'my-token', ['read', 'write']);
$token = $manager->find($rawToken);
$manager->revoke($token->id);

Register the bundled migration before migrating:

database/migrations/2024_01_01_000000_create_personal_access_tokens_table.php

Console command

# Generate a personal access token for a user
php ez auth:token <user_id> <name> [--abilities=read,write] [--expires=3600]

Classes

Class	Description
Auth	Static façade — login(), logout(), user(), check(), id(), hashPassword(), verifyPassword()
AuthServiceProvider	Registers Auth singleton; optionally injects UserProviderInterface
UserInterface	Contract for authenticated user objects — getAuthId()
UserProviderInterface	Contract for user lookup — findById(), findByToken()
AuthorizableInterface	Optional contract for authorization checks on user objects
PersonalAccessToken	Immutable value object — isExpired(), can()
PersonalAccessTokenManager	Token CRUD — create(), find(), revoke(), rotate(), pruneExpired()
AuthMiddleware	Bearer token middleware (static list or provider mode)
JwtMiddleware	JWT Bearer token middleware with optional blacklist and user resolution
JwtManager	Issues and validates HMAC-HS256 JWTs
JwtBlacklist	Cache-backed token blacklist (SHA-256 keyed)
JwtServiceProvider	Registers JwtManager and JwtBlacklist
Console\TokenCommand	auth:token CLI command

License

MIT — Andreas Uretschnig