Download the PHP package vaclavvanik/oauth2-token without Composer

oauth2-token

A small contract for obtaining an OAuth 2.0 access token, plus a caching decorator that hands back the token it already has until it is about to expire - so an API client is not doing a token round-trip before every request.

Why

Plenty of APIs hand out a short-lived bearer token in exchange for a client id and secret (the client_credentials grant, or something close to it). The token fetch is trivial; the annoying part is not doing it every time. This package is that annoying part, done once:

• TokenProvider - a one-method contract, getToken(TokenRequest $request): AccessToken, that you implement once per API (or pull in a ready-made implementation).
• CachingTokenProvider - a decorator around any TokenProvider that stores the token and reuses it until it is within a refresh delta of expiry, then fetches a new one. It is a RefreshableTokenProvider, so it also lets you forget() a token that was revoked before its expiry.
• ExpirationValidator - a JWT access token expires on its own exp claim rather than a guessed lifetime; a JWT without exp, and every non-JWT token, falls back to the expires_in from the token response.
• Pluggable storage: in-memory for a single process, a JSON file for sharing across processes, or your own Cache\Repository.

No HTTP client is pulled in - the transport lives in the concrete TokenProvider you provide; the only runtime dependencies are the psr/http-client and psr/http-message interface packages. Tested on PHP 7.3 - 8.5.

Install

Usage

Implement the contract

fromValidatedArray() needs the token lifetime to be knowable - either an expires_in in the response, or a JWT access_token with an exp claim - otherwise it throws. If your provider returns an opaque token with a lifetime you only know from its docs, supply it yourself:

Wrap it with caching

Use the token

getToken() returns a cached token when one is still valid and only calls the wrapped TokenProvider when the cache misses or the stored token is within the refresh delta of expiry. Tokens are cached per client id + secret + scope set.

There is no lock around the fetch: if several processes hit a cold or expired cache at the same moment, each fetches its own token. Fine for most providers; if yours rate-limits the token endpoint hard, pre-warm the cache or add locking in a custom Repository.

Forcing a refresh

The cache cannot see a token that was revoked before its expiry - the API just starts rejecting it. RFC 6750 says that is a 401 with error="invalid_token", but check what your API actually does (some use 403). Catch it, forget() the token, and retry once with a fresh one:

forget() is part of RefreshableTokenProvider (what the factory returns), not the base TokenProvider interface - type-hint RefreshableTokenProvider where you need it.

Refresh delta

By default a token is treated as expired 60 seconds before its real expiry, leaving room for clock skew and the request itself. Override it when building the decorator:

Storage

Cache entries are keyed by Cache\Key - an md5 of the client id, secret and the TokenRequest scope string. Scopes are a set, so ['read', 'write'] and ['write', 'read'] share one entry. The secret is used only to derive the hash: this package never exposes it through its API and never puts it in an exception or a log line.

Exceptions

getToken() fails in one of two ways, and callers are meant to tell them apart:

• Psr\Http\Client\NetworkExceptionInterface - the token endpoint could not be reached (DNS, connection refused, TLS, timeout). Transient; a retry may succeed. The TokenProvider contract lets this bubble up from the implementation untouched, so catch (NetworkExceptionInterface $e) around getToken() works.
• Exception\Runtime - the exchange itself failed (a malformed response body, a token whose lifetime cannot be determined, a failed cache write, a clock error). Not retryable without a change.

Everything else this package throws implements Exception\Exception:

• Exception\ErrorResponse - the token endpoint answered with an OAuth error; carries getError(), getErrorDescription(), getErrorUri() and the PSR-7 getResponse(). Throw new ErrorResponse($response, $error, $description, $uri) (only $error is required) from your TokenProvider implementation on a non-2xx response.
• Exception\Runtime - as above. Corrupt cache content is not an error - it degrades to an empty cache that rebuilds itself - but a cache file that cannot be read or written at all (permissions, a directory) throws this, carrying the underlying reason.
• Cache\Exception\NotFound - a repository was asked to load() a key it does not hold.

Run check - coding standards and php-unit

Install dependencies:

Run check:

Changelog

Please see CHANGELOG for more information what has changed recently.

License

The MIT License (MIT). Please see License File for more information.