Product Decisions This Supports
- Session lifetime and "stay logged in" UX. The core tradeoff this package encodes — short-lived access tokens plus longer-lived refresh tokens with server-side rotation — is exactly the dial that decides how long a user stays signed in on web and mobile without re-authenticating. That is a product decision, not just an architecture one, and this package gives you a concrete reference model for pricing it out (e.g. 15-minute access token / 30-day sliding refresh).
- Revocation and forced-logout capability. Because refresh tokens are persisted and rotated, it supports features product teams routinely request late and expensively: "log out all devices," "sign out everywhere after a password change," admin-initiated session termination, and per-device session lists. If those are on the roadmap, retrofitting revocation onto stateless JWTs is a re-architecture — worth deciding now.
- Token theft containment. Refresh-token rotation with reuse detection (invalidating a token family when an old token is replayed) is a security control you can put in front of a security review or a customer questionnaire. It turns "we use JWTs" from a red flag into a defensible answer.
- API and multi-client strategy. Whether first-party mobile apps, SPAs, and third-party integrations share one token model or get separate ones. This package's pattern (one refresh-token record per client/device) directly informs that segmentation.
- Build vs. buy for identity. Use it as the cheap end of the spectrum when scoping: the "build it ourselves" estimate should be compared against a hosted IdP (Auth0, Cognito, Clerk, WorkOS) and against a framework-native solution. A package like this is a useful floor for the build estimate — it shows the minimum viable surface (token model, rotation, storage, cleanup).
- Roadmap sequencing. If refresh tokens are a prerequisite for mobile app store approval, long-session consumer UX, or an enterprise security review, this defines an unblocking dependency that should be scheduled before those items, not after.
Important caveat for the decision record: despite being described as a Laravel/PHP package in the brief, this is a Symfony bundle, not a Laravel package. For a Laravel codebase it is a pattern reference, not a dependency — Laravel teams would use Sanctum or Passport. That distinction changes the decision from "adopt" to "read and reimplement," which is a much cheaper commitment but also delivers no maintenance transfer.
When to Consider This Package
Consider it when:
- You are on Symfony (or a Symfony-based stack such as API Platform) and want refresh-token rotation without hand-rolling token storage, rotation, and reuse detection.
- You need the mechanics, not the whole identity platform. If MFA, social login, SSO, and user management are already handled elsewhere, a focused token bundle is the right shape of dependency.
- You are willing to vendor or fork. With zero stars, zero dependents, and a zero score, this is effectively unvetted, low-adoption software. Treat it as source material you own, not as a maintained upstream. Budget for reading it end to end and pinning or vendoring it.
- You need a reference implementation to scope a build. Even if you never install it, a compact working example of rotation plus revocation is a fast way to pressure-test your own design and your estimate.
- You are pre-product-market-fit and optimizing for speed over long-term dependency hygiene, and the auth surface is first-party only.
Look elsewhere when:
- You are on Laravel. Use Sanctum for first-party SPA/mobile tokens or Passport if you need full OAuth2. Adopting a Symfony bundle here means fighting the framework.
- You need a certified or audited identity provider. Compliance regimes (SOC 2 with customer-facing evidence, HIPAA, PCI) generally favor a hosted IdP with a published security program over an unmaintained community bundle.
- You need OAuth2/OIDC as a protocol — authorization code flow with PKCE, consent screens, third-party clients. That is
league/oauth2-server territory or a hosted provider, not a refresh-token helper.
- You need a maintenance guarantee. Zero dependents and zero stars is a signal to check commit recency, open issues, and whether this is a fork of a more established project (the pattern strongly resembles the older
gesdinet/jwt-refresh-token-bundle). If upstream is healthier, track upstream and cite this as a fork.
- You need multi-region token storage or very high write throughput. Per-request refresh-token writes to a relational table become a hot path; validate against your scale assumptions before committing.
How to Pitch It (Stakeholders)
For executives: We are deciding how long users stay logged in and how quickly we can cut off a compromised account. Today that is either undocumented or handled implicitly, which shows up as friction in security reviews and as rework when a customer asks for "log out all devices." There is an open-source example of the standard solution — short-lived access credentials plus a revocable, rotating refresh token — that we can use to size the work. It is not a dependency we would take on as-is: it is a small, low-adoption Symfony component, and our stack is Laravel, so we would implement the pattern with framework-native tooling rather than adopt the code. The recommendation is a bounded piece of work, not a platform migration, and it removes a recurring blocker in enterprise deals. The alternative — a hosted identity provider — is faster to stand up but introduces per-user pricing and a vendor we would depend on for login.
For engineering: This is a Symfony bundle implementing refresh-token rotation over JWT with persisted tokens, which is the correct shape for revocation and reuse detection. We are not installing it — different framework and effectively unmaintained (no stars, no dependents, no community). We are using it as a design reference: it shows the minimum schema (token id, hashed value, user, device/client, expiry, revoked-at, parent/family for reuse detection), the rotation flow, and the cleanup job. Our implementation should map onto Sanctum or Passport primitives rather than a new package, and we should confirm the security properties ourselves: hashed-at-rest storage, single-use rotation, family revocation on replay, refresh-token binding to client, and a defined max absolute lifetime independent of rotation. Please treat upstream adoption as out of scope unless someone finds the maintained parent project and it clears a dependency review.