Oauth2 Client Bundle Laravel Package

Getting Started

Reality check first. This package last shipped in July 2014, has no stars and no dependents. It targets the Symfony 2.x era and will not install cleanly into a Symfony 4+ app without shimming. Treat it as a reference implementation rather than a dependency you drop into a current project.

Minimal steps to evaluate it:

1. Inspect before installing. Clone the repo and read composer.json (check the symfony/* constraints and php requirement against your runtime), then the README.md, then DependencyInjection/Configuration.php — that last file is the authoritative list of every config key, more reliable than the docs.
2. If you want to run it anyway, install into a Symfony 2.8/3.x sandbox first:

   composer require lasso/oauth2-client-bundle
   

3. Register the bundle in app/AppKernel.php:

   new Lasso\Oauth2ClientBundle\LassoOauth2ClientBundle(),
   

   (Verify the exact FQCN from the repo's *Bundle.php — the vendor namespace and folder case may not match the Composer name.)
4. Add the block to app/config/config.yml with client id, client secret, token/authorization endpoints, redirect URI, and scopes. Check Configuration.php for the exact tree names.
5. Look at Resources/config/services.xml to see which service IDs you actually get — typically a client factory, a token storage service, and a token-refresh service.

First use case: a server-to-server call to an API behind the OAuth2 client_credentials grant. That is the shortest path to a working request and the fastest way to confirm the bundle's token storage and refresh logic actually work.

Implementation Patterns

Service injection over static helpers. Pull the token provider out of the container and inject it into your API client rather than calling the container inside business logic:

class CrmApiClient
{
    private $httpClient;
    private $tokenProvider;

    public function __construct($httpClient, TokenProviderInterface $tokenProvider)
    {
        $this->httpClient = $httpClient;
        $this->tokenProvider = $tokenProvider;
    }

    public function getAccount($id)
    {
        $token = $this->tokenProvider->getAccessToken();

        return $this->httpClient->get('/accounts/'.$id, [
            'headers' => ['Authorization' => 'Bearer '.$token],
        ]);
    }
}

Wrap the vendor client. Whatever Guzzle/HTTP layer the bundle uses, wrap it. That way, when you migrate to league/oauth2-client + knpuniversity/oauth2-client-bundle (the realistic end state), only the wrapper changes, not every call site.

Configure one client per upstream API. If you talk to more than one OAuth2-protected service, define separate named client configurations with separate token storage keys. Do not share a token store across issuers.

Token refresh as a decorator. Put refresh logic in a decorator around your token provider so callers never think about expiry:

public function getAccessToken()
{
    $token = $this->store->fetch($this->key);

    if (!$token || $token['expires_at'] <= time() + 60) {
        $token = $this->refresh($token['refresh_token'] ?? null);
        $this->store->save($this->key, $token);
    }

    return $token['access_token'];
}

Retry-on-401 at the wrapper level. Even with refresh, clock skew and revoked tokens cause 401s. Catch the 401, invalidate the cached token, refresh once, retry once — then fail loudly.

User-scoped flows. For authorization-code flows, the redirect URI must exactly match what is registered with the provider, including trailing slash and scheme. Store the state parameter in the session and verify it on the callback.

Gotchas and Tips

• It is abandoned. No security patches, no PHP 8 support, no Symfony 5/6 compatibility. Before relying on it, check whether your app's PHP version will even autoload it. If you're on anything modern, budget the time to port.
• Composer will fight you. Constraint conflicts with symfony/framework-bundle are near-guaranteed. Do not use --ignore-platform-reqs to force it into production — that hides real incompatibilities.
• Undocumented config keys. Read DependencyInjection/Configuration.php directly. When a key is rejected, the error message from the bundle's own validation is the fastest clue.
• Token storage is plaintext. Old bundles commonly serialized tokens to the filesystem or the DB unencrypted. Encrypt refresh tokens at rest; they are long-lived credentials.
• Refresh tokens may not rotate. Some providers issue a new refresh token on every refresh and invalidate the old one. If your store doesn't persist the new value, the next refresh fails silently. Always write back the full token response.
• Clock skew. Compare expiry against time() minus a buffer (30–120s), and prefer the provider's expires_in over a hardcoded TTL.
• Debugging 401s. Log the token's expires_at, the scopes it was issued with, and the exact Authorization header sent. Scope mismatches present identically to expiry and are the most common cause.
• Container caching masks config changes. After editing config, clear the cache in the relevant environment (app/console cache:clear --env=prod) — old Symfony bundles read config at compile time in ways that surprise you.
• Extension point. The cleanest escape hatch is the token provider service: alias your own implementation to the bundle's service ID in services.yml and keep the rest of the bundle intact while you migrate underneath it.
• Migration target. Plan for league/oauth2-client (the maintained PSR-18 client) plus knpuniversity/oauth2-client-bundle for Symfony integration. The grant types map 1:1, so the port is mostly mechanical.