Social User Bundle Laravel Package

Getting Started

This is a Symfony 2 bundle, not a Laravel package. There is no service provider, no facade, and no way to install it into a Laravel app without effectively reimplementing Symfony's bundle/kernel/security stack. Day-to-day leverage for a Laravel developer is therefore indirect: read it as a reference implementation of the "OAuth + password login in one user table" pattern, and use laravel/socialite + laravel/fortify (or laravel/ui) for the real thing.

If you inherit a legacy Symfony 2 app that already uses it, the minimum path is:

1. Confirm the app still resolves its composer.json constraints (this bundle's last release was 2014-11-04; expect Symfony ~2.x and PHP 5.x).
2. composer require userfriendly/social-user-bundle using the era-appropriate Composer/PHP.
3. Register the bundle in app/AppKernel.php and import its routing in app/config/routing.yml.
4. Configure OAuth clients (client_id, client_secret, redirect_uri) in app/config/config.yml.
5. Wire the bundle's user provider into the form_login and OAuth firewalls in app/config/security.yml.
6. Create/extend your User entity from the bundle's base model.

Where to look first, in order:

• README.md — setup and the canonical config sample.
• DependencyInjection/Configuration.php — the authoritative config tree; the README lags it.
• Resources/config/services.* — what is actually wired and which ids you can override.
• Security/ and Entity/ (or Model/) — the auth flow and the user contract.
• Tests/, if present — the fastest way to see expected provider responses.

First use case: add a "Sign in with GitHub" button next to the existing username/password form, and create a local user on first OAuth login. That is the bundle's whole reason to exist; everything else is variation on it.

Implementation Patterns

• Dual authentication in one firewall. The typical setup is one firewall with form_login plus the bundle's OAuth entry point (or two firewalls with a shared user provider). Keep the OAuth firewall after the form-login firewall; ordering in security.yml decides which listener wins.
• User entity as the integration seam. Your User implements the bundle's user interface and extends its base class. Store the provider name and provider user id as separate columns (e.g. oauth_provider, oauth_id) — not just the email — so one account can link multiple providers and re-linking is idempotent.
• First-login provisioning via events/listeners. The bundle exposes registration/connect hooks. Do account creation, role assignment, and welcome-email dispatch in a listener rather than in a controller, so the same logic applies to every provider.
• Connect vs. login. Treat "log in with provider" and "link provider to existing account" as distinct flows. Linking should require an authenticated session and a confirmation step, or you will silently merge accounts on matching email addresses.
• Provider abstraction. Provider-specific quirks (Facebook fields, Google scopes, Twitter's email gap) belong in a small adapter/service, not sprinkled across controllers.
• Override, don't fork. Almost everything can be replaced by redefining a service id in your app config or overriding a template in app/Resources/. Do that; the repo is archived and you will never get upstream fixes.
• Testing. Stub the OAuth HTTP client at the adapter boundary with a canned provider payload; never let tests hit a real provider. Assert both the happy path and the "provider returned no verified email" path.

Gotchas and Tips

• Archived since ~2014. No security fixes, no provider API updates. The OAuth endpoints and scopes it targets (Google+, old Facebook Graph, Twitter v1.1) have largely been retired. Assume the wire format is stale before assuming your config is wrong.
• Symfony 2 is EOL. PHP 5.x-era code, no symfony/security-bundle beyond 2.x. Composer will fight you the moment anything modern is in the tree. Do not try to bridge it into a Laravel app; port the pattern instead.
• state parameter / CSRF. Older bundles often omit or under-validate the OAuth state parameter. Verify it yourself; this is a real CSRF vector in social login.
• Email is not a reliable key. Providers may return a null or unverified email (notably Twitter). Decide up front whether you require a verified email, prompt for one, or disallow the provider.
• Redirect URI mismatch is the most common failure. It must match byte for byte what is registered with the provider, including trailing slash and scheme, and must match across config.yml, the provider console, and any proxy/X-Forwarded-* rewrite.
• Tokens in the database. If the bundle persists access tokens, check whether they are encrypted and whether refresh/expiry is handled. Usually they are not — plan to store as little as possible.
• Debugging. Dump the raw provider response inside your adapter before it hits the user mapper; most "user not created" bugs are a missing field or a scope the app never requested. Use the Symfony profiler's request/security panels and app/logs/dev.log; firewall misordering is invisible until you look at the listener chain.
• Extension points to prefer: custom user provider, event subscriber on the registration/connect event, and service overrides for the OAuth client. Avoid editing vendor code — you cannot patch it downstream.
• The Laravel-native equivalents, if you are porting: laravel/socialite for the provider dance, laravel/fortify for the password/session side, a social_accounts table (user_id, provider, provider_id, token) for linking, and a SocialiteWasCalled/login event listener for first-login provisioning. That mapping is the only thing this bundle is still good for.