Getting Started

Minimal Setup

Install the package:

composer require socialiteproviders/manager

Publish the config (optional, but recommended for customization):

php artisan vendor:publish --provider="SocialiteProviders\Manager\ManagerServiceProvider"

Register providers in config/services.php:

'providers' => [
    'github' => [
        'client_id' => env('GITHUB_CLIENT_ID'),
        'client_secret' => env('GITHUB_CLIENT_SECRET'),
        'redirect' => env('GITHUB_REDIRECT_URI'),
    ],
    'custom-provider' => [
        'client_id' => env('CUSTOM_CLIENT_ID'),
        'client_secret' => env('CUSTOM_CLIENT_SECRET'),
        'redirect' => env('CUSTOM_REDIRECT_URI'),
    ],
],

Use Socialite as usual:

use Laravel\Socialite\Facades\Socialite;

$user = Socialite::driver('github')->user();

First Use Case: Adding a New Provider

Find or create a provider (e.g., from SocialiteProviders).
Add it to config/services.php under the providers key.

Use it in your routes/controllers:

Route::get('/auth/custom-provider', function () {
    return Socialite::driver('custom-provider')->redirect();
});

Implementation Patterns

Core Workflow: Extending Socialite

Event-Based Extension: Create a listener for SocialiteWasCalled to dynamically extend Socialite:

// app/Providers/EventServiceProvider.php
protected $listen = [
    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        \App\Listeners\ExtendSocialite::class,
    ],
];

// app/Listeners/ExtendSocialite.php
public function handle(SocialiteWasCalled $socialiteWasCalled) {
    $socialiteWasCalled->extendSocialite('custom-provider', \App\Providers\CustomProvider::class);
}

Dynamic Config Overrides: Override provider config at runtime (e.g., per-tenant or environment-specific):

$config = new \SocialiteProviders\Manager\Config(
    env('CUSTOM_CLIENT_ID'),
    env('CUSTOM_CLIENT_SECRET'),
    route('custom-provider.callback'),
    ['scope' => ['read:user', 'write:org']]
);
Socialite::driver('custom-provider')->setConfig($config)->redirect();

Stateless Mode: Enable stateless mode for Lumen or performance-critical apps:
```
Socialite::stateless()->driver('github')->user();
```

Integration Tips

Lumen Support: Works out-of-the-box. No additional setup required.

Multi-Tenant Providers: Use dynamic config to switch providers per tenant:

$tenantConfig = Tenant::find($tenantId)->provider_config;
$config = new \SocialiteProviders\Manager\Config(
    $tenantConfig['client_id'],
    $tenantConfig['client_secret'],
    route('tenant.callback', $tenantId)
);
Socialite::driver('github')->setConfig($config)->redirect();

A/B Testing: Dynamically toggle providers based on user segments:

$provider = request()->user()->isInSegment('experiment')
    ? 'discord'
    : 'github';
Socialite::driver($provider)->redirect();

Access Token Response: Extend AbstractProvider to expose full OAuth response:

// In your custom provider class
public function getAccessTokenResponseBody() {
    return $this->response->getBody();
}

Access it via:

$user = Socialite::driver('custom-provider')->user();
$refreshToken = $user->accessTokenResponseBody['refresh_token'];

Provider Development

Create a New Provider:

Extend \SocialiteProviders\Manager\OAuth2\AbstractProvider (for OAuth2) or \SocialiteProviders\Manager\OAuth1\AbstractProvider (for OAuth1).
Implement getAuthUrl(), getAccessToken(), and getUserByToken().

Example:

namespace App\Providers;

use SocialiteProviders\Manager\OAuth2\AbstractProvider;

class CustomProvider extends AbstractProvider {
    protected $scopes = ['read', 'write'];

    public function getAuthUrl($state) {
        return $this->buildAuthUrlFromBaseUrlWithScopes('https://custom-api.com/oauth/authorize', $state);
    }

    public function getAccessToken($code) {
        $response = $this->getHttpClient()->post($this->getTokenUrl(), [
            'form_params' => [
                'code' => $code,
                'client_id' => $this->clientId,
                'client_secret' => $this->clientSecret,
                'redirect_uri' => $this->redirectUrl,
                'grant_type' => 'authorization_code',
            ],
        ]);
        return json_decode($response->getBody(), true);
    }

    public function getUserByToken($token) {
        $response = $this->getHttpClient()->get('https://custom-api.com/api/user', [
            'headers' => ['Authorization' => 'Bearer ' . $token],
        ]);
        return json_decode($response->getBody(), true);
    }
}

Override Built-in Providers:
- Create a provider with the same name as the built-in one (e.g., facebook). The manager will automatically use your custom implementation.

Gotchas and Tips

Pitfalls

Event Listener Timing:
- Ensure your SocialiteWasCalled listener is registered in EventServiceProvider. If not, custom providers won’t load.
- Fix: Verify the listener is in the $listen array and the event is dispatched (it is by default in the manager).
Config Precedence:
- Runtime setConfig() overrides .env values. If you need .env to take precedence, avoid calling setConfig().
- Tip: Use setConfig() only for dynamic overrides (e.g., per-tenant or environment-specific settings).
Stateless Mode Quirks:
- Stateless mode disables session storage. Useful for Lumen but may break stateful flows (e.g., multi-step OAuth).
- Workaround: Use stateless mode only for stateless providers (e.g., OAuth2 with PKCE).
Provider Naming Conflicts:
- If you override a built-in provider (e.g., facebook), ensure your class name matches exactly (e.g., FacebookProvider). Mismatches will fall back to the default.
OAuth1 vs. OAuth2:
- OAuth1 providers require additional setup (e.g., Server class). Refer to existing OAuth1 providers (e.g., Twitter) for examples.
- Tip: Use AbstractProvider for OAuth2 and AbstractServer for OAuth1.
Access Token Response Body:
- Not all providers expose the full response body by default. Extend AbstractProvider and implement getAccessTokenResponseBody() if needed.
- Example:
```
public function getAccessTokenResponseBody() {
    return $this->tokenResponse;
}
```
Laravel Version Compatibility:
- The package supports Laravel 6–12. If you’re on an older version, use v3.x of the manager.
- Check: Run composer why-not socialiteproviders/manager to verify compatibility.

Debugging Tips

Provider Not Loading:
- Check if the SocialiteWasCalled event is fired. Add a temporary listener:
```
public function handle(SocialiteWasCalled $event) {
    \Log::info('Socialite called for driver: ' . $event->driver);
}
```
- Verify the provider name matches exactly (case-sensitive).
Config Issues:
- Use dd($config) to inspect the config object before calling setConfig().
- Ensure .env variables are loaded (e.g., php artisan config:clear if testing locally).
OAuth Errors:
- Enable Guzzle logging to debug HTTP requests:
```
$client = new \GuzzleHttp\Client([
    'debug' => fopen('guzzle.log', 'w'),
]);
$provider->setHttpClient($client);
```
- Check the provider’s raw response for errors (e.g., 400 Bad Request).
Performance Bottlenecks:
- Deferred instantiation should prevent slowdowns, but complex providers (e.g., OAuth1) may add latency.
- Optimization: Cache provider instances if reused frequently:
```
static $instances = [];
if (!isset($instances[$driver])) {
    $instances[$driver] = Socialite::driver($driver);
}
return $
```

Manager Laravel Package