README

Panulat JWT

Lightweight JWT authentication for Panulat REST APIs.

blcklab/panulat-jwt adds JWT support to Panulat through a service provider, middleware, and route middleware aliases.

Install

composer require blcklab/panulat-jwt

blcklab/panulat-core is installed automatically as a package dependency.

Register the Provider

Add the JWT service provider to your Panulat application providers:

Panulat\Jwt\JwtServiceProvider::class

The provider registers:

Panulat\Jwt\JwtService
Panulat\Jwt\JwtMiddleware
auth middleware alias
jwt middleware alias

Configuration

The JWT service uses your application JWT configuration.

Example:

return [
    'secret' => panulat_env('JWT_SECRET', 'change-me'),
    'ttl' => 3600,
];

For production, always use a strong secret:

JWT_SECRET=your-secure-random-secret

Creating Tokens

use Panulat\Jwt\JwtService;

$jwt = new JwtService('your-secret-key');

$token = $jwt->encode([
    'sub' => '1',
    'email' => 'user@example.com',
    'exp' => time() + 3600,
]);

Decoding Tokens

$claims = $jwt->decode($token, ['sub']);

The second argument defines the required claims. If a required claim is missing, or if the token is invalid, a JWT exception is thrown.

Protecting Routes

Use the auth or jwt middleware alias to protect routes:

$router->get('/v1/me', [MeController::class, 'show'], ['auth']);

or:

$router->get('/v1/me', [MeController::class, 'show'], ['jwt']);

The middleware reads the bearer token from the request header:

Authorization: Bearer <token>

Request Attributes

After a valid token is decoded, the middleware attaches JWT data to the request:

$request->getAttribute('user');
$request->getAttribute('jwt_claims');

user contains the resolved user value from the token when available.

jwt_claims contains the decoded token claims.

Example Controller

use Panulat\Http\Request;
use Panulat\Http\Response;

final class MeController
{
    public function show(Request $request): Response
    {
        return Response::json([
            'data' => [
                'user' => $request->getAttribute('user'),
                'claims' => $request->getAttribute('jwt_claims'),
            ],
        ]);
    }
}

Error Handling

Invalid, expired, missing, or malformed tokens are converted into Panulat unauthorized responses by the middleware.

Typical response status:

401 Unauthorized

Scope

This package intentionally stays small.

Included:

HS256 JWT encode and decode support
JWT validation
Expiration handling
Required claim checks
Panulat middleware integration
auth and jwt middleware aliases

Not included:

OAuth
Sessions
Refresh token storage
Database token blacklist
Roles and permissions
Social login

Those features can be added through separate packages or application code.

Quality Checks

composer stan
composer test
composer check

License

MIT

blcklab / panulat-jwt

Maintainers

Package info

Statistics

Security