Oauth2 Server Exception Manager Laravel Package

Product Decisions This Supports

• Build vs. buy on OAuth2 error handling (marginal). This is not a feature; it is glue. It maps OAuth2 server exceptions (invalid_request, invalid_client, invalid_grant, invalid_scope, unsupported_grant_type, unauthorized_client) into correct HTTP responses — status codes, WWW-Authenticate headers, Cache-Control: no-store. The PM decision it informs is "do we hand-roll error mapping in our token endpoint, or adopt a library that already encodes RFC 6749 semantics?"
• API contract / conformance roadmap. Relevant if you have a workstream around OAuth2/OpenID conformance, partner integrations, or security-questionnaire answers (SOC 2, pen-test findings on token endpoint behavior). Consistent, spec-correct error responses reduce integration support tickets from third-party clients.
• Dependency and maintenance posture. With zero stars, zero dependents, and a zero score, the real decision this supports is a risk decision: whether to take on a low-traction transitive dependency versus writing ~50–100 lines of exception-to-response mapping ourselves. That is a one-to-two-day engineering task, not a quarter.
• Decisions it does not support. It gives you no authorization server, no grant types, no token storage, no client registry, no consent UI, no Laravel service provider or config. Do not let it anchor a "we'll build our own IdP" decision.

When to Consider This Package

Adopt only when all of the following hold:

• You are already running spomky-labs/oauth2-server (or the corresponding Symfony bundle) at a version that declares this as a dependency, and you want its exception handling rather than custom middleware.
• You need uniform exception→PSR-7/PSR-15 response conversion across multiple endpoints and don't want to maintain that mapping yourself.
• You have verified the last commit date, supported PHP versions, and open security advisories — and are comfortable that "zero dependents" means near-zero community backstop.

Look elsewhere when:

• Greenfield. Use league/oauth2-server with league/oauth2-server-bundle, or Laravel Passport, which already ships league's exception types and response handling. This package would be redundant.
• You want to buy, not build. A hosted IdP (Auth0, Okta, Keycloak, Cognito) removes this entire category of decision.
• You are Laravel-first. This is a framework-agnostic PHP library, not a Laravel package — no auto-discovery, no publishable config. Integration cost is yours to absorb.
• Maintenance signals matter to your architecture review. Zero stars and zero dependents should trigger a "can we vendor or reimplement this?" question rather than an adoption.

How to Pitch It (Stakeholders)

To executives: This is a small, free plumbing library that makes our OAuth2 token endpoint return standards-compliant error responses — the kind auditors and integration partners check. It ships no user-facing feature and costs nothing to license. The tradeoff is community traction: essentially nobody else uses it, so if it breaks, we fix it. Recommendation: treat it as a "reimplement in a day" item, not a strategic dependency.

To engineering: It is exception-to-HTTP-response glue for the Spomky OAuth2 server ecosystem. If we are not already on that stack, skip it — league/oauth2-server (and therefore Passport) already solves this. If we are, evaluate whether its current release supports our PHP version, then decide between adopting it and writing the mapping ourselves; the latter is low-effort and removes an unmaintained dependency from our tree.