Laravel Socialite Laravel Package

Getting Started

• Install: composer require overtrue/laravel-socialite. If you're still on Laravel 10, pin to ^4.0.1 — 4.1.0 is the Laravel 11 line, so treat the upgrade as tied to your framework upgrade, not as an independent package bump.
• Auto-discovery: The Overtrue\LaravelSocialite\SocialiteServiceProvider and the Socialite facade alias are registered automatically. No manual config/app.php edits needed on Laravel 11.
• Publish config: php artisan vendor:publish --provider="Overtrue\LaravelSocialite\SocialiteServiceProvider" to get config/socialite.php. Put credentials in .env (*_CLIENT_ID, *_CLIENT_SECRET, *_REDIRECT_URI) and reference them from the config file — never inline secrets.
• Where to look first: config/socialite.php for driver setup, then the package's manager/facade surface (Socialite::driver('github')). Check composer.json of the package for the exact illuminate/* and overtrue/socialite constraints, since the driver list and minimum PHP version come from the underlying library, not this wrapper.
• First use case: an OAuth login flow. Two routes — one that calls Socialite::driver($provider)->redirect() and one that receives the callback and calls ->user(). That's the whole loop; everything else is mapping that user onto your own users table.

Implementation Patterns

• Two-route flow, one controller:

  Route::get('/auth/{provider}/redirect', [OAuthController::class, 'redirect']);
  Route::get('/auth/{provider}/callback', [OAuthController::class, 'callback']);
  

  Keep the callback route behind the web middleware group — the state/session check depends on it.
• Resolve, don't trust: treat the returned user as a claim. Look up by (provider, provider_id) first, fall back to email match only if you're confident the provider verifies emails, and only then create. Store the provider id in a social_accounts table if a user can link multiple providers.

  $social = Socialite::driver($provider)->user();
  $account = SocialAccount::firstOrNew(['provider' => $provider, 'provider_id' => $social->getId()]);
  

• Stateless mode for APIs: Socialite::driver($provider)->stateless() when the flow starts from a mobile app or a token-based SPA. You lose CSRF protection on the callback, so add your own signed state parameter and validate it.
• Scopes and extra params: chain ->scopes([...]) and ->with(['prompt' => 'consent']) on the redirect call. Read them from config rather than hardcoding, so you can request extra scopes (e.g. refresh tokens) per environment.
• Persist tokens immediately on the callback if you need API access later — access tokens are short-lived and refresh tokens are only returned on the first consent in many providers.
• Drive it through config, not code: a config('socialite.providers') array plus {provider} route parameter lets you add a new provider without touching the controller. Validate the provider name against the config keys before passing it to driver().
• Test without hitting the network: mock the driver in feature tests (Socialite::shouldReceive('driver->user')->andReturn($fakeUser)) and assert the redirect and callback behaviour, user creation, and duplicate-account handling separately.

Gotchas and Tips

• Upgrade path: 4.1.0 is a Laravel 11 compatibility release. If you're upgrading the app to Laravel 11, bump this package in the same PR and re-run your auth feature tests — the wrapper itself is thin, so most breakage will surface from Laravel's middleware/provider changes, not from the package.
• Laravel 11 skeleton differences: no app/Http/Kernel.php. If your callback needs session or cookie middleware, register it in bootstrap/app.php (->withMiddleware(...)), and register any custom listeners/providers in bootstrap/providers.php. Older tutorials referencing Kernel.php will mislead you.
• Redirect URI mismatch is the number one failure. The value registered with the provider must byte-for-byte match what you send. Behind a load balancer, configure trusted proxies (TrustProxies) or the generated URL will be http:// and the provider will reject it.
• Config caching: after changing config/socialite.php or .env on a deployed environment, run php artisan config:clear / config:cache. Stale cached config is the usual cause of "it works locally".
• State mismatch / InvalidStateException: almost always a missing session, a cookie domain mismatch, or a user who took too long. Don't retry silently — redirect back to the login page with a flash message.
• Driver availability: this package wraps overtrue/socialite; providers outside its built-in list need an additional driver package. Check available drivers before promising a provider to a stakeholder.
• Handle provider errors explicitly: wrap ->user() in a try/catch for InvalidStateException and HTTP/request exceptions. Providers return error=access_denied on the callback when users cancel — treat that as a normal path, not a 500.
• Email is not identity: some providers return null or unverified emails. Decide up front whether to reject, prompt for email, or create an account without one — this is a product decision the code must encode, and it's the most common source of account-takeover bugs in social login.
• Extension point: if you need custom behaviour (token refresh, extra API calls), wrap the facade in your own service rather than calling Socialite:: throughout the app. That keeps the package boundary in one place and makes a future swap or upgrade cheap.