Oauth Bundle Laravel Package

Getting Started

Orientation step: confirm which side of the fence you're on. rz/oauth-bundle is a Symfony bundle that extends HWIOAuthBundle and wires its social-login flow into RzUserBundle. It is not installable in a Laravel app, is archived, and has zero dependents. If you're on Laravel, your day-to-day equivalent is Laravel Socialite — but the patterns inside this package (identity → local user mapping) are worth reading before you write that code.

If you own a legacy Symfony app already pulling this in, read in this order:

1. composer.json — the pinned versions of hwi/oauth-bundle, friendsofsymfony/user-bundle, and the Symfony minor are the real constraint; they decide whether your next upgrade is possible. Everything else is secondary.
2. DependencyInjection/ — the config tree is the actual public API. It exposes the hwi_oauth extension points, the user-provider wiring, and the service ids you can override.
3. Resources/config/ — service definitions. Diff what the bundle registers vs. what it decorates on top of HWIOAuthBundle; the decorated services are the shim.
4. Security/ — the resource-owner-to-user bridge. This is the only genuinely custom piece. Everything else is glue.

First use case (pattern, not install): "log in with GitHub/Google, map remote identity to a local user." Concretely: an oauth_accounts table keyed by (provider, provider_user_id) with an FK to users.id. That mapping is the one concept worth lifting into your Laravel app, and it's ~40 lines of Socialite.

Implementation Patterns

The useful work is extracting the patterns and rebuilding them on a supported stack. These are the ones the bundle encodes well:

• Provider → local user resolution. Never treat the OAuth identity as the user; treat it as a lookup key. Pattern: findByProviderAndId() → else match by verified email → else create. Same logic the bundle's user provider runs; same logic you'll want in Laravel.
• Login vs. connect flows. HWIOAuthBundle separates "authenticate an existing session" from "link an account to a logged-in user." In Laravel, mirror with two route pairs: /auth/{provider}/redirect + /callback (login, unauthenticated) and /settings/connections/{provider}/link + /callback (connect, behind auth middleware). Never let a callback create-and-login a user when the intent was to link — that's an account-takeover vector.
• Stateless providers. SPAs, mobile, and API tokens need Socialite::driver($p)->stateless(). This is the analogue of HWIOAuthBundle's stateless resource owners. Get the state/cookie discipline right on day one or you'll debug InvalidStateException for a day.
• Custom providers. Socialite::extend() is the direct analogue of registering a custom resource owner in hwi_oauth.resource_owners. Put these in app/Socialite/ and register via a service provider — not inline in a controller.
• Thin controller, thick action. The bundle plugs into security.firewalls.main.oauth; the Laravel boundary is middleware + Auth::login(). Resolve identity in an action class (OAuthUserResolver), then hand off to your normal login path so session regeneration, guards, and any 2FA hooks still run. Don't call Auth::login() from deep inside the resolver.
• Expose the mapping as an interface. Bind OAuthUserResolver in the container. That's the extension point the original bundle should have shipped with; it's what makes swapping providers (or adding Apple) cheap later.

Gotchas and Tips

• It does nothing standalone. Requiring it without a live HWIOAuthBundle firewall and RzUserBundle produces "service not found" errors — not helpful ones. The common misdiagnosis is a missing bundle registration when the real cause is a missing hwi_oauth firewall config key.
• Abandoned dependency chain. The whole lineage is end-of-life: HWIOAuthBundle is superseded by Symfony's own authenticator system, FOSUserBundle is deprecated, and rz/oauth-bundle is archived on top of both. Upgrading Symfony will force you off all three at once — scope it as one migration, not three.
• Security boundary risk. OAuth is auth. An unmaintained shim in that path means no CVE response. If it must stay in legacy, fork and vendor it with an internal owner and a removal date — don't leave it as a floating require.
• Debugging on legacy Symfony: enable the profiler's security panel and dump the firewall's token after callback. Most integration issues are the resource owner returning a response the user provider can't match (email mismatch, missing scope, casing), which surfaces as "authentication failed" rather than a mapping error.
• Config quirks: the hwi_oauth config is firewall:-scoped, so a typo in the resource-owner name silently fails to register the listener and the callback URL 404s. Grep for the exact resource-owner id in Resources/config/ before assuming the bundle didn't load.
• Extension points worth mimicking: the bundle's best idea is that user resolution is a service you can replace. Replicate that in Laravel by binding OAuthUserResolver — it's the difference between a swap being a two-file change and a week of archaeology.
• Migration rule of thumb: treat "archived + zero dependents" as a hard stop for new adoption. The only legitimate day-to-day use of this package today is read-only reference during migration — inventory the integration surface (listeners, user provider, routing, DI config), then delete it in one sweep and rebuild the mapping on Socialite.