Oauth2 Server Bearer Token Laravel Package

Getting Started

This package is a low-level, framework-agnostic piece of the spomky-labs/oauth2-server (v1 era) stack — it does not ship a Laravel ServiceProvider, config file, or facade. You are pulling in a single concern: the RFC 6750 "Bearer" token type, which knows how to find an access token in an incoming request and how to format the responses when one is missing or invalid.

Minimal install:

composer require spomky-labs/oauth2-server-bearer-token

You almost certainly also need the parent library (spomky-labs/oauth2-server) unless it is already present — this package only contributes the Bearer token type class.

Where to look first:

• SpomkyLabs\OAuth2ServerBearerToken\TokenType\Bearer — the only meaningful class. It implements the library's TokenTypeInterface and exposes getAccessToken(), createAccessTokenResponse(), and the token-type parameter (bearer).
• The parent library's TokenTypeManager, AccessTokenManager, and EndPoint classes — this package plugs into those.

First use case: register the bearer type with the token type manager so that the authorization/token endpoints can issue and validate tokens that carry the Bearer type.

// AppServiceProvider::register()
use SpomkyLabs\OAuth2ServerBearerToken\TokenType\Bearer;

$this->app->singleton(Bearer::class);
$this->app->extend(TokenTypeManager::class, function (TokenTypeManager $manager) {
    $manager->addTokenType(app(Bearer::class));
    return $manager;
});

Implementation Patterns

Middleware to extract the token. The whole reason you want this package is that Bearer::getAccessToken(RequestInterface $request) implements the RFC 6750 lookup order for you. Wrap it in middleware that resolves the token from the PSR-7 request, then hands off to your own guard/user resolution:

$psrRequest = (new PsrHttpFactory(...))->createRequest($laravelRequest);
$token = $this->bearer->getAccessToken($psrRequest); // null if not found
abort_if(! $token, 401, 'Missing bearer token');

Issuing tokens. The bearer type also builds the token response body for you (access_token, token_type, expires_in, optional refresh_token). Point the parent library's token endpoint at Bearer::createAccessTokenResponse() rather than hand-rolling JSON — this keeps you compliant and avoids the classic "token_type": "Bearer" vs "bearer" casing bug.

Error responses with WWW-Authenticate. When authentication fails, the type produces the correct WWW-Authenticate: Bearer realm="...", error="invalid_token", error_description="..." header. Emit this from your exception handler for the token-authenticated routes so clients can distinguish invalid_request / invalid_token / insufficient_scope.

Composition with the parent stack. Typical wiring order in a provider is: TokenTypeManager → Bearer → AccessTokenManager → EndPoint\Token and EndPoint\Resource. Treat the bearer type as a stateless collaborator; keep it a singleton.

Scope enforcement. Scope checking is not in this package — it lives in the parent's access-token manager. Use this package strictly for extraction + response formatting, and enforce scopes in a separate guard/policy layer.

Gotchas and Tips

• Maintenance status. This is a legacy v1 piece of the Spomky-Labs OAuth2 universe; the ecosystem moved on to oauth2-framework (and, in Laravel land, Laravel Passport or league/oauth2-server). Evaluate whether you're inheriting an existing install before choosing it for greenfield work.
• No PSR-7 bridge. Laravel's Request is not a PSR-7 message. You must convert with a factory (Diactoros/Nyholm) before calling getAccessToken(). A common source of confusion when people call it on $request directly.
• Extraction precedence matters. Per RFC 6750, the Authorization: Bearer <token> header takes precedence; the access_token body and query parameters are fallbacks (and query-string tokens are discouraged because they leak into logs). Don't add your own extractor "just in case" — it will disagree with the package.
• Case sensitivity. Token type is compared case-insensitively by spec (bearer/Bearer); don't hand-compare the scheme string elsewhere in your middleware.
• Debugging missing tokens. If getAccessToken() returns null, verify the header is being forwarded end-to-end — proxies (Nginx, load balancers) frequently strip Authorization, and CORS preflight will not carry it. Log $request->getHeaders() at the edge before blaming the package.
• Config quirks. There is no config/oauth2.php here. Realm, token TTL, and signing keys belong to the parent server config; the bearer type only reads them via injected collaborators.
• PHP constraints. The v1 family pins older PHP and PSR-7 versions; check compatibility before adding to a modern (PHP 8.2+) app or you'll fight Composer resolution.
• Extension points. If you need custom lookup (e.g. header name), subclass Bearer and override getAccessToken() rather than forking — the parent manager only depends on the TokenTypeInterface.