Oauth2 Server Access Token Manager Laravel Package

Getting Started

This package is a thin contract layer for managing OAuth2 access tokens inside the bshaffer/oauth2-server-php stack (the Spomky-Labs family split storage concerns into separate manager packages: access tokens, refresh tokens, auth codes, clients, scopes). It is not a full OAuth2 server and it is not a storage implementation — it gives you interfaces and usually an abstract base class you implement against your own persistence.

Minimal steps:

1. composer require spomky-labs/oauth2-server-access-token-manager (you will almost certainly also need bshaffer/oauth2-server-php and the sibling managers for refresh tokens, clients, and scopes).
2. Look first at the interface in src/ — typically AccessTokenManagerInterface and any AbstractAccessTokenManager. That file is your real spec; the README is thinner than the code.
3. Read the method list. Expect something close to createAccessToken, updateAccessToken, getAccessToken, getAccessTokenByRefreshToken, deleteAccessToken, and getExpiredAccessTokens/revocation helpers.
4. Implement the interface against your database (PDO, Doctrine, Redis) — the package will not do this for you.
5. Wire your implementation into the OAuth2 Server and TokenController from oauth2-server-php.

First use case: a minimal PDO-backed access token manager. Create a table oauth_access_tokens(token, client_id, user_id, expires, scope), implement the interface by mapping methods to SELECT/INSERT/UPDATE, and register it with the server. That is the 90% path.

Implementation Patterns

Extend the abstract class, don't implement from scratch. If an AbstractAccessTokenManager is provided, extend it and only fill in persistence. The abstract class typically owns token generation, hashing, and expiry arithmetic; you supply save/load/delete. This is the intended extension pattern and keeps you aligned with future patch releases.

Manager is the boundary, not the source of truth. The OAuth2 Server decides token lifecycle (expiry, refresh linkage, revocation triggers); the manager just persists and retrieves. Do not re-implement grant logic here — you will fight the TokenController.

Reuse the shape across the sibling managers. Access token, refresh token, auth code, and client managers are deliberately parallel. Build one repository (Doctrine entity or a single PDO table helper) and instantiate multiple managers over it. This is why the family exists — consistency across grant storage.

Token lookup is by string. Almost every method signature takes the raw token string as the key. Design your schema around that: token (primary key or unique), client_id, user_id, expires (integer unix time), scope. Index expires so you can prune expired tokens efficiently.

Refresh linkage. getAccessTokenByRefreshToken implies the access token row stores or can join to the refresh token. Either store refresh_token on the access token row or keep a separate relation table. Pick one; the interface only promises the lookup, not the schema.

Lifecycle integration. Typical day-to-day flow: client posts credentials → server creates access + refresh tokens via your managers → resource server validates bearer token via a ResourceController that calls getAccessToken → revocation route calls deleteAccessToken. Your manager is hit on every authenticated request, so make getAccessToken a single indexed query.

Test seam. Because the manager is an interface, stub it in unit tests to exercise the Server without a database. Wrap the real implementation in a decorator that caches tokens (Redis, in-process array) to take the hot path off the DB in production.

Gotchas and Tips

• This is effectively an abandoned, zero-dependents package. The 0 score / 0 dependents is a red flag: pin exact versions, vendor the code if necessary, and expect to own it. The Spomky-Labs team later moved on to a different OAuth2 server (spomky-labs/oauth2-server), so namespaces and APIs from that era may not match what you find in current bshaffer/oauth2-server-php docs.
• Interface drift across oauth2-server-php versions. Method signatures (createAccessToken vs newer token-object APIs) changed between 3.x and 4.x. Check the manager's composer constraint against your server version before upgrading either side — mismatches show up as fatal "must be compatible" errors at class load, not at runtime.
• Tokens are stored as strings. Never store plaintext bearer tokens in production; the interface gives you the raw token, so hash (SHA-256) before persistence and look up by hash. Keep the raw value only in the response.
• Expiry is your job to honor. The manager does not automatically refuse expired tokens; getAccessToken typically returns whatever is in storage. Filter expires > time() in your query or validate in the resource controller, otherwise expired tokens remain valid until pruned.
• Pruning is manual. Schedule DELETE FROM oauth_access_tokens WHERE expires < :now (or call any getExpiredAccessTokens-style helper). No automatic GC exists at this layer.
• Refresh token cleanup cascade. When an access token is deleted, decide whether the paired refresh token dies too — the interface will not tell you. Orphaned refresh tokens are a common source of "token still works after logout" bugs.
• Debugging: enable the oauth2-server-php server's error callbacks and log the exact token string plus the manager return value at the getAccessToken boundary. Most "invalid_grant" / "invalid_token" issues trace to a manager returning null because of a timezone (string vs int expires) mismatch.
• Extension points: the only meaningful ones are (a) decorate the manager for caching, (b) swap the token generator/hasher in the abstract class, (c) subclass the abstract base to add audit columns (created_at, last_used_at). Do not monkey-patch internals — the package surface is small enough that a clean reimplementation is often cheaper than fighting it.
• Consider writing your own thin manager. Given the package is essentially an interface with no dependents and no active maintenance, implementing the ~6 methods directly against your ORM is frequently less risk than pulling another abandoned dependency into your auth path.