Laravel Passport Cache Token Laravel Package

Getting Started

The package swaps Laravel Passport's TokenRepository for a cache-backed decorator, so every bearer-token request avoids a DB hit on oauth_access_tokens. Minimum steps:

1. composer require overtrue/laravel-passport-cache-token
2. Laravel's package auto-discovery registers the service provider — no manual config/app.php edit needed on Laravel 5.5+.
3. Publish the config if you want to tune TTL/store: php artisan vendor:publish --provider="Overtrue\\LaravelPassportCacheToken\\PassportCacheTokenServiceProvider" (tag: config).
4. Hit any Passport-protected route and confirm a cache key like passport:token:* appears (e.g. via php artisan cache:table + a quick Cache::get() tinker call).

First use case to validate: grab a token via /oauth/token, call a guarded endpoint twice, and watch the DB query log — you should see the oauth_access_tokens select fire once, then disappear on the second request. If it still fires, the repository wasn't decorated (usually a config cache issue — see Gotchas).

Laravel 10 support arrived in 3.2.0, so on a Laravel 10 app you can install straight from ^3.2 without pinning. It still works on 9.x; there's nothing in this release that drops older versions.

Implementation Patterns

Default decorator setup. The service provider rebinds League\OAuth2\Server\Repositories\AccessTokenRepositoryInterface behind the scenes. You don't touch your AuthServiceProvider. Just install and go — this is the "zero-config" path and covers 90% of apps.

TTL aligned to token lifetime. Set cache.ttl in the published config to something shorter than your Passport Passport::tokensExpireIn() value. Tokens are read-heavy and rarely mutated, so a TTL of a few minutes is a good trade-off — long enough to skip the DB on bursts, short enough that a revoked token disappears from cache before anyone can abuse it.

Separate cache store. If your default cache is array (tests) or file, consider a dedicated Redis/Memcached store for token caching so you get consistent behavior across app servers and easy FLUSHDB-style invalidation. Point cache.store at it in the config.

Testing. In feature tests, prefer Cache::flush() in setUp() or use the array store, otherwise a token cached in one test can bleed into another. Combine with Passport::actingAs() for authenticated request tests — the cache layer is transparent there.

Multi-guard / multi-tenant apps. The cache key is derived from the token string, not the user, so tokens from different guards/tenants won't collide as long as the token values differ (they will). No special handling needed.

Revocation flow. If your app supports POST /oauth/token revocation or refresh tokens, wire an explicit Cache::forget() in your logout handler — the package doesn't observe revocation events. This is the main integration tip for OAuth-correctness.

Gotchas and Tips

• Revoked tokens stay valid until cache expiry. The decorator only caches lookups; it doesn't invalidate on revoke. Keep TTL modest (2–5 min) or hook Laravel\Passport\Events\AccessTokenCreated/revocation manually.
• config:cache mismatch. Because the provider binds during boot, a stale config cache from before installing the package will leave the original repository in place. Run php artisan config:clear after install — this is the #1 "it's not caching" cause.
• Don't cache for the /oauth/token issuing endpoint. That path writes tokens, not reads them, so nothing to gain; if you've wrapped other repositories, keep the write path uncached.
• Token expiry vs TTL skew. If TTL > token lifetime, you can serve a technically expired token from cache. Either clamp TTL below Passport::tokensExpireIn() or accept the risk and rely on the OAuth server's own validation of expires_at (it checks the cached record's timestamp, so this is usually fine — but know it).
• Cache::tags() is unavailable on file/database stores. If you plan on tag-based invalidation, use Redis or Memcached.
• Debugging: log the key prefix when tokens are read (Cache::get('passport:token:'.$tokenId)) via an Event::listen on Illuminate\Cache\Events\CacheHit/CacheMiss scoped to your prefix — fastest way to verify the decorator is active without dumping queries.
• Extension point: the repository is a thin wrapper around Passport's; if you need per-IP pinning or extra claims in the cached payload, extend the package's repository class and rebind it in your own AppServiceProvider rather than forking.
• Version pin: use ^3.2 — 3.1.0 lacks the Laravel 10 constraint adjustments and can trigger Composer conflicts on fresh L10 installs.