Jwt Refresh Token Bundle Laravel Package

Product Decisions This Supports

• Session lifetime policy. The bundle makes the access-token/refresh-token split a tunable product setting rather than a code change: short-lived JWTs for API calls, a configurable refresh TTL (default 30 days) that defines how long a user can be away before re-entering a password. That is a UX decision, not just a config value.
• Build vs. buy for auth plumbing. Refresh-token rotation, server-side revocation storage, expiry sweeping (gesdinet:jwt:clear), and firewall wiring are commodity. This is the "don't build it" line item on a roadmap.
• "Stay signed in" and mobile session persistence. Long-lived mobile sessions, background app resumption, and "remember me" all depend on a refresh mechanism. This is the prerequisite ticket that unblocks them.
• Revocation as a shippable capability. Stateless JWTs can't be killed before expiry. Adding a token table turns "sign out all devices," forced logout after password change, compromised-account response, and support-driven session kills into features rather than incident-response scripts.
• Security posture tradeoffs you must own. Single-use (rotating) tokens limit blast radius from a stolen token but raise re-login and support cost when rotation races occur. A ten-year TTL is a permanent password stored in your database — a policy choice with audit and retention consequences, not just a number.
• Data lifecycle scope. You now own a table: backups, retention, purge cadence, and who can query it. That belongs in the data inventory conversation.

When to Consider This Package

• Stack fit is the first gate: this is a Symfony bundle, not a Laravel package. It requires Symfony Security, LexikJWTAuthenticationBundle, PHP 8.2+, and Symfony 6.4 / 7.2+ / 8.0+. On Laravel, stop and evaluate Sanctum, Passport, or tymon/jwt-auth instead — do not let a "PHP package" label pull it into a Laravel build-vs-buy doc.
• Adopt when: you're already on Symfony with Lexik JWT, you need server-side revocation/rotation rather than purely stateless tokens, and you're willing to own one Doctrine entity plus a reviewed migration. Doctrine ORM/ODM is supported, and a custom ObjectManager is possible if you don't use Doctrine.
• Look elsewhere when: you need OAuth2/OIDC (third-party identity, scopes, consent) — that's league/oauth2-server or a hosted IdP; you want zero-database stateless auth; you need a vendor SLA; or you want social login, which this does not provide.
• Operational gotchas that become PM-visible incidents:
  • check_path must match the refresh route or refresh requests 401 — a misconfiguration the docs call out explicitly.
  • auto_mapping: false or multi-entity-manager setups throw "No identifier/primary key specified" until the bundle mapping is named.
  • doctrine:migrations:diff compares the whole database and can drop tables Doctrine doesn't know about unless schema_filter is set. Mandate human review of generated migrations in the rollout checklist — this is a data-loss risk, not a lint issue.
• Maturity caveats to verify, not assume: ~712 stars and a single-maintainer profile suggest fork-readiness planning. The "0 dependents" and "last release 2026-08-05" metadata look like reporting artifacts — confirm against Packagist and GitHub before citing maintenance cadence or adoption in a decision memo.

How to Pitch It (Stakeholders)

For executives

• What it buys: refresh-token rotation, revocation, TTL policy, and expired-token cleanup for roughly a sprint of engineering we'd otherwise spend on undifferentiated auth plumbing. MIT licensed, no per-MAU cost, no vendor lock-in.
• Commercial value: unblocks "stay signed in" on mobile and converts "please log me out everywhere" from a support escalation into a self-serve feature. Also shortens security review, because it's a well-known pattern with a small, auditable surface.
• What it doesn't buy: differentiation. This is table stakes. It also does not cover social/third-party login — that's a separate IdP decision.
• Risk in one sentence: a small, single-maintainer open-source dependency — mitigate with a pinned version, a fork-readiness note, and a hard rule that no auto-generated migration runs unreviewed.

For engineering

• Saves building: token persistence (ORM/ODM/custom ObjectManager), rotation on refresh, the expiry cleanup command, and the firewall authenticator wiring.
• Quality signals: PHPStan level 10, Rector, CI test coverage, active release line, and unusually thorough upgrade documentation (2.0/2.1/2.2/3.0 plus a Rector-assisted path from 1.5).
• Obligations accepted: one entity, one human-reviewed migration, a schema_filter, check_path alignment with the route, and HTTPS (recommended by the project). Bundle-declared authenticator priority means refresh runs before JWT on the same firewall — don't reorder the YAML expecting file order to matter.
• Decisions we need from product: single-use vs. reusable refresh tokens, TTL value, and what happens to existing sessions on password change.