Manager Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require socialiteproviders/manager
   

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

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

3. Register a provider (e.g., GitHub):

   composer require socialiteproviders/github
   

4. Add the provider to config/services.php:

   'github' => [
       'client_id' => env('GITHUB_CLIENT_ID'),
       'client_secret' => env('GITHUB_CLIENT_SECRET'),
       'redirect' => env('GITHUB_REDIRECT_URI'),
   ],
   

5. Extend Socialite (via an event listener):

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

6. Create the listener (e.g., app/Providers/GitHubExtendSocialite.php):

   namespace App\Providers;
   
   use SocialiteProviders\Manager\SocialiteWasCalled;
   
   class GitHubExtendSocialite
   {
       public function handle(SocialiteWasCalled $socialiteWasCalled)
       {
           $socialiteWasCalled->extendSocialite('github', \SocialiteProviders\GitHub\GitHubExtendProvider::class);
       }
   }
   

7. Use Socialite as usual:

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

First Use Case: Quick GitHub OAuth

// routes/web.php
Route::get('/login/github', function () {
    return Socialite::driver('github')->redirect();
});

Route::get('/login/github/callback', function () {
    $user = Socialite::driver('github')->user();
    // Handle user data (e.g., create/update in DB)
    return redirect('/dashboard');
});

Implementation Patterns

1. Provider Registration Workflow

Adding a New Provider

1. Install the provider package:

   composer require socialiteproviders/{provider-name}
   

2. Add credentials to .env (e.g., TWITTER_CLIENT_ID, TWITTER_CLIENT_SECRET).
3. Extend Socialite via an event listener (as shown in Getting Started).
4. Use the provider:

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

Overriding Built-in Providers

• Create a new provider with the same name as the built-in (e.g., facebook).
• The manager will automatically override the default Socialite provider.
• Example: Override Google’s default provider with a custom implementation.

2. Dynamic Configuration

Runtime Provider Config

Useful for per-tenant credentials or A/B testing:

$config = new \SocialiteProviders\Manager\Config(
    env('TENANT_1_GITHUB_CLIENT_ID'),
    env('TENANT_1_GITHUB_CLIENT_SECRET'),
    route('tenant-1.github.callback'),
    ['team_id' => 123] // Additional config
);

return Socialite::driver('github')
    ->setConfig($config)
    ->redirect();

Stateless Mode

Enable for Lumen or high-performance APIs:

// In your listener:
$socialiteWasCalled->setStateless(true);

• Pros: Reduces memory usage by not loading providers until called.
• Cons: Slightly higher latency on first use (provider instantiation).

3. Custom Provider Development

Template for a New Provider

1. Extend the abstract class:

   namespace App\Providers;
   
   use SocialiteProviders\Manager\OAuth2\AbstractProvider;
   use Laravel\Socialite\Contracts\User;
   
   class CustomProvider extends AbstractProvider
   {
       protected $scopes = ['read', 'write'];
   
       protected function getAuthUrl($state)
       {
           return $this->buildAuthUrlFromBase('https://custom-auth.example.com/oauth/authorize', $state);
       }
   
       protected function getTokenUrl()
       {
           return 'https://custom-auth.example.com/oauth/token';
       }
   
       protected function getUserByToken($token)
       {
           $response = $this->getHttpClient()->get('https://custom-auth.example.com/api/user', [
               'headers' => ['Authorization' => 'Bearer ' . $token],
           ]);
   
           return json_decode($response->getBody(), true);
       }
   
       protected function mapUserToObject(array $user)
       {
           return (new User())->setRaw($user)->map([
               'id' => $user['id'],
               'nickname' => $user['username'],
               'name' => $user['full_name'],
               'email' => $user['email'],
           ]);
       }
   }
   

2. Register the provider in your listener:

   $socialiteWasCalled->extendSocialite('custom', \App\Providers\CustomProvider::class);
   

Accessing Raw Response Body

For providers needing refresh_token or expires_in:

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

4. Multi-Tenant Provider Routing

Dynamic provider selection based on tenant:

// In your listener:
public function handle(SocialiteWasCalled $socialiteWasCalled)
{
    $tenant = Tenant::find(request('tenant_id'));
    $providerName = $tenant->auth_provider; // e.g., 'github' or 'gitlab'

    $socialiteWasCalled->extendSocialite($providerName, \SocialiteProviders\GitHub\GitHubExtendProvider::class);
}

• Use case: SaaS apps where tenants configure their preferred OAuth provider.

5. Event-Driven Extensions

Modify User Data Before Saving

Listen to SocialiteProviders\Manager\Events\UserFetched:

// app/Providers/EventServiceProvider.php
protected $listen = [
    \SocialiteProviders\Manager\Events\UserFetched::class => [
        'App\Listeners\UpdateUserFromSocialite',
    ],
];

// app/Listeners/UpdateUserFromSocialite.php
public function handle(UserFetched $event)
{
    $user = $event->user;
    $user->setAttribute('custom_field', $user->raw['custom_data']);
}

Log Provider Usage

use SocialiteProviders\Manager\SocialiteWasCalled;

public function handle(SocialiteWasCalled $socialiteWasCalled)
{
    logger()->info("Provider called: {$socialiteWasCalled->providerName}");
}

6. Lumen Integration

1. Register the service provider in bootstrap/app.php:

   $app->register(\SocialiteProviders\Manager\ManagerServiceProvider::class);
   

2. Use stateless mode (recommended for Lumen):

   $socialiteWasCalled->setStateless(true);
   

3. Avoid global Socialite binding (Lumen doesn’t use the service container by default):

   $provider = new \SocialiteProviders\GitHub\GitHubExtendProvider(
       new \GuzzleHttp\Client,
       new \SocialiteProviders\Manager\Config(
           env('GITHUB_CLIENT_ID'),
           env('GITHUB_CLIENT_SECRET'),
           url('/callback')
       )
   );
   $user = $provider->user();
   

Gotchas and Tips

Pitfalls

1. Provider Not Found

   • Cause: Forgetting to register the provider in the SocialiteWasCalled listener.
   • Fix: Verify the listener is in EventServiceProvider::$listen and the class namespace is correct.
   • Debug: Check Laravel logs for Class 'SocialiteProviders\GitHub\GitHubExtendProvider' not found.

2. Double Registration

   • Cause: Multiple listeners extending the same provider.
   • Fix: Use a single listener or add a guard:

     if (!$socialiteWasCalled->hasProvider('github')) {
         $socialiteWasCalled->extendSocialite('github', \SocialiteProviders\GitHub\GitHubExtendProvider::class);
     }
     

3. Stateless Mode Latency

   • Cause: Providers load on first use, causing delays.
   • Fix: Pre-load providers in a queue job or command if performance is critical.

4. Environment Variables Not Loaded

   • Cause: .env variables not published or misspelled.
   • Fix: Run php artisan config:clear or verify .env keys match config/services.php.

5. OAuth1 vs. OAuth2 Confusion

   • Cause: Mixing AbstractProvider classes (e.g., using OAuth2 for Twitter).
   • Fix: Use `\SocialiteProviders\Manager\OAuth1