Jwt Library Laravel Package

Getting Started

This package is a low-level JWT building block—not meant for direct use. Install the full web-token/jwt-framework meta-package (composer require web-token/jwt-framework) instead. Start by configuring signing/encryption keys (via KeyManager), then integrate core services like JWTBuilder and JWTValidator into Laravel’s service container. The official docs provide foundational examples—adapt Symfony-style service definitions for Laravel using app()->singleton().

Implementation Patterns

• Encapsulate JWT logic: Create dedicated services (e.g., AuthService::issueToken(), AuthService::validateToken()) that delegate to JWTBuilder/JWTValidator—avoid sprinkling low-level JWT calls across controllers.
• Laravel auth integration: Hook JWTValidator into custom guards or middleware to validate access tokens; reuse Laravel’s Request/Response objects for seamless integration (e.g., JWTValidator::validate($request->bearerToken(), $checks)).
• Key rotation via JWKS: Fetch remote JWKS endpoints (e.g., from Auth0 or self-signed OAuth2 providers) using JWKSet::createFromJson(), cache results (e.g., via Laravel Cache), and inject into JWTValidator.
• Custom validation checks: Extend Check\Check to enforce app-specific rules (e.g., require organization_id claim), and register them as services for reusability across token types.

Gotchas and Tips

• Hidden dependencies: You must manually install sibling packages (web-token/jwt-signature, web-token/jwt-encryption)—this package alone throws Class not found errors. Check composer.lock to confirm all components are present.
• Overly generic exceptions: JWTValidationException lacks context—always call $e->getErrors() and log the exact failed checks + original payload (redact secrets!) to debug invalid tokens.
• Strict mode is non-negotiable: Always enable strict validation (new Validator(null, true)) to enforce header/payload immutability—otherwise, tokens can be tampered with post-validation.
• Laravel cache gotcha: Cache JWKSet objects serializes them safely—but avoid caching raw JSON responses; parse then cache the JWKSet instance to prevent runtime deserialization errors.
• No Laravel ecosystem alignment: Unlike tymon/jwt-auth, this library doesn’t provide auth('jwt') middleware or Token model hooks—expect to write boilerplate for auth guards, middleware, and exception handlers.