quillphp/jwt

JWT Auth middleware for the Quill PHP framework

dev-main 2026-04-04 18:33 UTC

Requires

• php: ^8.3
• firebase/php-jwt: ^7.0
• quillphp/quill: ^0.0.1

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• QuillPHP Team

• framework
• php
• middleware
• auth
• jwt
• quill

README

JWT Auth Middleware for the Quill PHP Framework.

This plugin intercepts requests, extracts the JWT from the Authorization header, decodes it using firebase/php-jwt, and injects the claims into the request context for downstream handlers to use.

Installation

composer require quillphp/jwt

Usage

use Quill\App;
use Quill\Jwt\JwtMiddleware;

$app = new App();

// Protect all routes
$app->use(JwtMiddleware::new([
    'secret' => 'your-super-secret-key'
]));

// Protected route
$app->get('/api/users', function(\Quill\Request $request) {
    // Access decoded token claims
    $user = $request->get('user');
    
    return [
        'id' => $user->id,
        'email' => $user->email
    ];
});

Configuration

You can customize the middleware behavior by passing an array to JwtMiddleware::new():

Option	Type	Default	Description
secret	string	""	Required. Your HMAC secret key or RSA public key.
algorithm	string	"HS256"	The algorithm used to sign the JWT.
header	string	"Authorization"	Which header to inspect for the token.
scheme	string	"Bearer"	The expected authorization scheme.
contextKey	string	"user"	The key where claims are stored in the Request context.
extractor	callable	null	Custom closure to extract the token: fn(Request $r) => ?string
error	callable	null	Custom error handler: fn(Request $r, Throwable $e) => mixed

Custom Token Extractor

If you need to extract the token from a cookie or a custom header:

$app->use(JwtMiddleware::new([
    'secret' => 'secret',
    'extractor' => function(\Quill\Request $request) {
        // Look in cookies first, fallback to header
        return $request->cookie('jwt-token') ?? $request->header('X-Api-Token');
    }
]));

Custom Error Responses

By default, an invalid token returns a 401 Unauthorized JSON format. You can override this:

$app->use(JwtMiddleware::new([
    'secret' => 'secret',
    'error' => function(\Quill\Request $request, \Throwable $e) {
        return new \Quill\HttpResponse('Authentication Failed', 401);
    }
]));

License

This package is open-sourced software licensed under the MIT license.