quillphp/jwt

JWT Auth middleware for the Quill PHP framework

dev-main 2026-04-05 23:29 UTC

Requires

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

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\Jwt\JwtMiddleware;

$app->use(JwtMiddleware::new([
    'secret' => 'your-256-bit-secret',
    'algorithm' => 'HS256',
]));

// 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:

```php
$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.