Laravel Jwt Laravel Package

Product Decisions This Supports

• Platform upgrade sequencing. v3.0 raises the floor to PHP 8.2+ and Laravel 11+, which makes this package upgrade a forcing function that should be sequenced after the runtime/framework upgrade and before any feature work that depends on the JWT changes. Treat it as a line item in the platform modernization roadmap, not as a standalone library bump.
• Build vs. buy for authentication/token handling. The package continues to own the token parsing/validation surface (facades, ParsedToken, middleware, request macros, exception classes) with an unchanged public API. That argues for staying on it rather than building in-house — v3.0 is a dependency-hygiene release, not an API churn release, so the switching cost of "buy/keep" stays low while the switching cost of "build" stays high.
• Asymmetric signing (RSA/RS256) as a viable product capability. The bug fix — validation now honors config('jwt.signer') instead of hard-coding HMAC SHA-256 — unblocks use cases that were previously broken or required workarounds: multi-service token issuance where only the auth service holds the private key, third-party/partner token verification, and any architecture where verifiers must not hold signing secrets. This is a genuine capability unlock, not just a defect fix, and should be reflected in roadmap conversations about service-to-service auth and key rotation.
• Security posture and key management roadmap. Being able to validate non-HMAC tokens through the standard ParsedToken::validate() path means key rotation, algorithm migration (HS256 → RS256), and separation of signing vs. verification duties become product-planning decisions rather than engineering hacks.
• Ecosystem/lifecycle currency. Explicit lcobucci/clock dependency, Laravel 13 support, PHPUnit 11, and GitHub Actions migration are signals the package is actively maintained against current framework versions. That supports a "keep" decision in a dependency review and reduces the risk of a future forced migration.

When to Consider This Package

Adopt / keep it when:

• You are on (or planning) PHP 8.2+ and Laravel 11+, and want JWT issuance/validation that tracks current Laravel releases (including Laravel 13).
• You need both symmetric (HMAC) and asymmetric (RSA/other) token validation, and specifically want the configured signer respected end-to-end — i.e., you were previously blocked by the hard-coded HS256 validation path.
• You want a small, stable public surface — facades, ParsedToken, middleware, request macros, exception classes — without a bespoke auth layer to maintain.
• You are comfortable with lcobucci/jwt as the underlying engine and do not reference its classes directly in your own code.

Look elsewhere or defer when:

• You are still on PHP 8.1 or Laravel 8–10. v3.0 will not install; you either upgrade the platform first or pin to the 2.x line and accept that you will not receive the signer-configuration fix. Note this is a security-relevant fix, so pinning has a real cost.
• Your codebase imports lcobucci/jwt v4 classes directly. The v5 upgrade guide must be worked through; the package's own API is stable, but your integration points may not be.
• You need OAuth2/OIDC flows, refresh-token grant machinery, or a full identity provider. This package handles JWT parsing and validation, not authorization-server responsibilities.
• You want a batteries-included auth product (social login, MFA, user management). This is a library, not a platform.

Pre-adoption checklist: confirm PHP and Laravel versions across all environments and CI images; audit for direct lcobucci/jwt imports; verify your config('jwt.signer') is set correctly (this fix changes behavior for anyone who was silently relying on HS256 validation succeeding regardless of config); and budget for a regression pass on middleware and request-macro call sites even though the API is unchanged.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a maintenance release of our JWT library, but it carries one meaningful fix: token validation now correctly respects the configured signing algorithm, which means we can finally support RSA-based tokens — the standard approach for verifying tokens across services without sharing a secret. The trade-off is a raised platform floor (PHP 8.2+, Laravel 11+), so the upgrade needs to be sequenced with our framework modernization rather than done in isolation. The library's own interface is unchanged, which keeps engineering risk and effort low; the main coordination cost is the platform prerequisite.

For engineering leads: Public API is unchanged — facades, ParsedToken methods, middleware, request macros, and exception classes behave as before. Two things to plan for: (1) the PHP 8.2 / Laravel 11 floor, and (2) lcobucci/jwt v4→v5, which only matters if we reference its classes directly — audit before scheduling. The signer fix is a behavior change for any environment where config('jwt.signer') was set to something other than HMAC but validation was silently falling back to HS256; treat those paths as needing explicit re-verification. Laravel 13 support and the move to GitHub Actions are maintenance positives that reduce our future upgrade exposure.