- What does bshaffer/oauth2-server-httpfoundation-bridge actually do?
- It is a thin adapter, not a framework. It wraps Symfony HttpFoundation Request objects behind OAuth2\HttpFoundationBridge\Request so bshaffer/oauth2-server-php can read grant parameters without re-parsing superglobals, and it exposes OAuth2\HttpFoundationBridge\Response as a JsonResponse implementing OAuth2\ResponseInterface. In a Laravel controller you convert the incoming request, pass it to the server, and return the bridge response in a few lines.
- How do I install bshaffer/oauth2-server-httpfoundation-bridge with Composer?
- Require bshaffer/oauth2-server-httpfoundation-bridge in your composer.json and run composer install or composer require. Match the bridge tag to your oauth2-server-php version when possible, since the bridge is versioned alongside the upstream library and v1.1 is the latest tag. There is no service provider, config file, database migration, or queue requirement.
- Does this bridge support Laravel 11 and Laravel 12?
- Laravel 11 and 12 ship Symfony 7 components, and the bridge's releases track Symfony 5 through 8 with PHP 8 compatibility fixes, so it is expected to build against current Laravel. The real compatibility question is whether bshaffer/oauth2-server-php itself supports your PHP version, because that library is the heavyweight dependency. Confirm both packages resolve together in a quick composer require before committing.
- Why use this instead of Laravel Passport or Sanctum?
- Laravel already ships Passport, built on league/oauth2-server, and Sanctum for token auth, so adopting this package is only justified if you are already standardized on bshaffer/oauth2-server-php. If you have production clients, tokens, and storage schema built around that server library, the bridge is the cheap, replaceable piece that makes the HTTP layer clean. If you are starting fresh, evaluate the server-library decision before the bridge.
- Why does my token endpoint fail to parse the grant request?
- The bridge reads grant parameters from the HttpFoundation request, so upstream middleware that consumes the input stream can break parsing. Logging middleware that calls getContent() without rewinding, or Laravel's TrimStrings and ConvertEmptyStringsToNull middleware mutating input, are the most common culprits in the wild. Verify this early in your proof of concept by inspecting what the bridge request actually contains.
- How do I return custom OAuth2 error payloads, content types, or headers?
- The bridge's Response is JSON-only out of the box, which covers standard OAuth2 success and error envelopes. For custom error shapes, non-JSON content types, or extra headers, implement OAuth2\ResponseInterface yourself and pass that object into the server instead of the bridge response. Budget a small amount of work for that if your API contract requires it.
- Is bshaffer/oauth2-server-httpfoundation-bridge abandoned or risky to depend on?
- It has roughly 51 stars and zero dependents, so there is no community backstop if the upstream server library stalls or a PHP or Symfony incompatibility appears. The mitigation is straightforward: the code surface is two small classes under the MIT license, so plan to vendor or fork it rather than depend on upstream responsiveness. Positive maintenance signals, such as tracking Symfony 5 through 8, materially lower the upgrade risk.
- How do I create the bridge request from an existing Laravel Request?
- Use OAuth2\HttpFoundationBridge\Request::createFromRequest($request) inside your controller or middleware, since Illuminate\Http\Request extends HttpFoundation Request. Static factories createFromGlobals and createFromRequestStack are also available if you are wiring this at a different layer. Do not use the raw OAuth2\Request class, or you lose the HttpFoundation integration.
- Does this package support PKCE, client credentials, or custom grant types?
- Grant type support comes from bshaffer/oauth2-server-php, not from the bridge, so the bridge only handles the request and response plumbing. PKCE for SPAs, client credentials for machine-to-machine tokens, and refresh token rotation must be supported by the upstream server or implemented by you. Non-standard grant types will require your own code on top of the server library.
- How do I test an OAuth2 controller built on this bridge?
- Construct Symfony HttpFoundation Request objects with the grant parameters and headers you want, wrap them with the bridge, and assert against the returned JsonResponse status code and body. Because the bridge has no database, queue, or config dependencies, the request and response layer is fast to test in isolation. Test the full token flow against your configured storage separately so you catch grant and client validation issues.