Oauth2 Server Exception Manager Bundle Laravel Package

Getting Started

Install the bundle alongside the OAuth2 server it complements:

composer require spomky-labs/oauth2-server-exception-manager-bundle

Register it in app/AppKernel.php (this is a Symfony 2.x-era bundle, so registerBundles() not bundles.php):

public function registerBundles()
{
    return [
        // ...
        new SpomkyLabs\OAuth2ServerExceptionManagerBundle\SpomkyLabsOAuth2ServerExceptionManagerBundle(),
        new SpomkyLabs\OAuth2ServerBundle\SpomkyLabsOAuth2ServerBundle(),
    ];
}

Where to look first: inspect Resources/config/services.xml in the bundle. There you will find the kernel.event_listener registration for kernel.exception (the "exception manager") and the concrete OAuth2ExceptionManager / error-response factory service it wires up. That file tells you the exact service IDs and the event priority, which is the single most important thing to understand before you start overriding anything.

First use case: throw one of the oauth2-server exception classes (e.g. SpomkyLabs\OAuth2ServerException\InvalidGrantException) from inside a controller or from a token endpoint. The bundle's listener intercepts it and returns an RFC 6749-compliant JSON error body (error, error_description, error_uri, and state when present) with the appropriate HTTP status, instead of a generic 500 page.

Implementation Patterns

Let exceptions bubble up, do not catch them. In OAuth2 token, authorize, and revoke endpoints, throw the library exception and let the listener translate it. Controllers stay thin:

if (!$this->validator->isValid($request)) {
    throw new InvalidRequestException('Missing parameter: grant_type');
}

Reuse the shared manager for manual responses. If you need to construct an error response outside the exception flow (e.g. in a custom firewall or a validation layer), fetch the manager from the container and call it with the exception. This keeps error formatting consistent between thrown and returned paths.

Compose with the OAuth2ServerBundle. The bundle assumes the surrounding OAuth2 server bundle is responsible for routing and authentication. Keep the exception manager purely as the response-serialization layer — do not put business validation logic into it.

Testing. Use Symfony's KernelBrowser (or the old WebTestCase client) and send a malformed token request (Content-Type: application/x-www-form-urlencoded with a bad grant). Assert on application/json content type and on the error key rather than the message text, since message strings are not part of the contract.

Custom error shapes. Subclass the manager or decorate the error-response factory service so you can attach extra fields (e.g. a trace_id) while still emitting the standard error / error_description pair. Register your class with the same service ID via a compiler pass or config.yml override — do not add a second kernel.exception listener, or you will duplicate responses.

Gotchas and Tips

This is legacy. The repository targets Symfony 2.x and the old oauth2-server library. Its API is incompatible with Symfony Flex, modern oauth2-server releases, and PHP 8.x. Treat this as reference material if you are maintaining an old Symfony 2 application, not as a component to pull into a new project. There are zero dependents on Packagist, which is a strong signal that nobody is exercising it against current stacks.

Listener priority matters. The bundle registers on kernel.exception with a specific priority. If you have your own exception listener (or the framework's ExceptionListener), make sure yours does not swallow OAuth2ExceptionInterface first. Verify order with debug:event-dispatcher kernel.exception (Symfony 3.4+); on older versions inspect the compiled container.

HTTP status codes are derived from the exception class. invalid_client and invalid_token map to 401; everything else in the invalid_request / unsupported_* family maps to 400. If you throw the wrong exception type, the status code will be wrong even though the JSON looks plausible — tests that only check the body will miss this.

state must be echoed. RFC 6749 §4.1.2.1 requires echoing the state parameter back on authorization-endpoint errors. If your state comes from a request object the listener cannot see, you must pass it into the exception or set it explicitly via the manager, otherwise clients reject the response.

Do not leak internals in error_description. Debug-mode Symfony error pages and the listener can both activate depending on kernel.debug. Confirm that in production debug is off and that unexpected exceptions (not OAuth2ExceptionInterface) still produce a plain 500 — the bundle should not be the last line of defense for non-OAuth errors.

Config quirks. With Symfony 2 extension classes, an empty Extension still requires the bundle to be registered; forgetting that causes "service not found" at runtime rather than at container compile time, which is confusing. Check app/config/config.yml loads the extension even if no configuration values are set.

Extension points. The realistic override surfaces are: (1) the exception-to-response manager service, (2) a custom OAuth2ExceptionInterface implementation for domain-specific errors, and (3) a decorator around the error-response factory. Avoid editing files under vendor/ — if you must patch, use a Composer patches entry or a composer.json fork so upgrades do not silently revert your fix.