Laravel Social Connections Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require maynagashev/laravel-social-connections
   

   Add the service provider to config/app.php:

   Maynagashev\SocialConnections\SocialConnectionsServiceProvider::class,
   

2. Publish Assets

   php artisan vendor:publish --tag=config
   php artisan vendor:publish --tag=models
   php artisan vendor:publish --tag=views
   

3. Configure Providers

   • Add credentials to .env (see gist).
   • Sync config/services.php with .env using env() helper.

4. Run Migrations

   php artisan migrate
   

5. First Use Case: OAuth Login Use the provided Blade component in your login/signup form:

   @socialLoginButtons
   

   This renders buttons for configured providers (e.g., Google, GitHub).

Implementation Patterns

Workflows

1. User Registration via Social Login

   • The package handles OAuth callbacks automatically. If the user doesn’t exist, it creates a new account.
   • Customization: Override SocialConnectionsServiceProvider::boot() to modify user creation logic:

     public function boot()
     {
         SocialConnections::extend('user', function ($user, $social) {
             $user->email = $social->email; // Force email update
         });
     }
     

2. Admin Management of Connections

   • Use the provided controller (SocialConnectionsController) to list/disconnect user connections.
   • Extend the resource routes in routes/web.php:

     Route::resource('social-connections', \Maynagashev\SocialConnections\Http\Controllers\SocialConnectionsController::class);
     

3. Dynamic Provider Configuration

   • Add/remove providers in config/social-connections.php:

     'providers' => [
         'google' => [
             'enabled' => true,
             'scopes' => ['email', 'profile'],
         ],
         'github' => [
             'enabled' => false,
         ],
     ],
     

4. Email Handling for Providers Without Email

   • The package prompts users to input an email if the provider (e.g., Twitter) doesn’t return one.
   • Customize the prompt in resources/views/vendor/social-connections/email-prompt.blade.php.

Integration Tips

• Laravel Fortify/Passport: Use the package alongside Fortify for unified auth:

  SocialConnections::authenticate('google', function ($user) {
      Auth::login($user);
  });
  

• Multi-Tenant Apps: Scope connections to tenants by overriding the SocialConnection model’s boot():

  protected static function boot()
  {
      parent::boot();
      static::addGlobalScope('tenant', function (Builder $builder) {
          $builder->where('tenant_id', auth()->user()->tenant_id);
      });
  }
  

Gotchas and Tips

Pitfalls

1. Provider Credentials Mismatch

   • Ensure .env and config/services.php are synced. Use php artisan config:clear if changes don’t reflect.
   • Debug Tip: Check storage/logs/laravel.log for OAuth errors (e.g., invalid client ID).

2. Email Handling Quirks

   • Some providers (e.g., LinkedIn) require explicit email scope permissions. Add to config/social-connections.php:

     'linkedin' => [
         'scopes' => ['r_emailaddress'],
     ],
     

   • If the package fails to prompt for email, manually trigger it in the callback:

     use Maynagashev\SocialConnections\Facades\SocialConnections;
     SocialConnections::promptForEmail($social);
     

3. Model Conflicts

   • The package publishes migrations for social_connections and social_users. If you’ve customized these tables, merge migrations manually.
   • Fix: Use --force in migrations or reset the database:

     php artisan migrate:fresh
     

4. CORS Issues with OAuth Redirects

   • Ensure your OAuth provider’s callback URL (e.g., http://your-app.test/auth/google/callback) is whitelisted in the provider’s dashboard.
   • Workaround: Use php artisan route:list to verify the callback route exists.

Debugging

• Enable Debug Mode Add to config/social-connections.php:

  'debug' => env('APP_DEBUG', false),
  

  This logs provider responses to storage/logs/social-connections.log.

• Test Locally with laravel-shift Use laravel-shift to mock OAuth responses during development:

  Shift::fake();
  Shift::add('google', 'user', [
      'id' => '123',
      'email' => 'test@example.com',
  ]);
  

Extension Points

1. Custom Social Providers Extend the SocialConnectionsManager to add unsupported providers:

   SocialConnections::extend('custom', function () {
       return Socialite::driver('custom')->scopes(['custom_scope']);
   });
   

2. Override Views Publish and modify the package’s views:

   php artisan vendor:publish --tag=views --force
   

   Edit resources/views/vendor/social-connections/....

3. Webhook Handling For providers with webhooks (e.g., GitHub), listen to events in EventServiceProvider:

   protected $listen = [
       'Maynagashev\SocialConnections\Events\SocialAccountUpdated' => [
           'App\Listeners\UpdateUserProfile',
       ],
   ];
   

4. Rate Limiting Throttle social logins in app/Http/Middleware/ThrottleSocialLogins.php:

   public function handle($request, Closure $next)
   {
       return $next($request)->throttle([
           'social' => 5, // 5 attempts per minute
       ]);
   }