Socialment Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require chrisreedio/socialment
   php artisan socialment:install
   

2. Add to Panel: In app/Providers/Filament/AdminPanelProvider.php:

   $panel->plugins([
       \ChrisReedIO\Socialment\SocialmentPlugin::make()
           ->registerProvider('github', 'fab-github', 'GitHub'),
   ]);
   

3. Configure Services: Add provider credentials to config/services.php (e.g., GitHub example):

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

4. Add Styling: Edit your panel's theme.css:

   @source '../../../../vendor/chrisreedio/socialment/resources';
   

First Use Case

Enable GitHub OAuth login for your Filament admin panel with a single button. Users can now log in via GitHub without managing traditional credentials.

Implementation Patterns

Core Workflow

1. Provider Registration: Register providers in your panel configuration with icon and label:

   ->registerProvider('google', 'fab-google', 'Google')
   ->registerProvider('azure', 'fab-microsoft', 'Azure AD')
   

2. Login Flow:

   • User clicks provider button → redirected to OAuth provider.
   • Provider authenticates user → redirects back to /login/{provider}/callback.
   • Socialment handles token exchange and user creation/login.

3. Custom User Logic: Use createUser closure to customize user creation:

   ->createUser(function (ConnectedAccount $account) {
       return User::firstOrCreate(
           ['email' => $account->userEmail],
           ['name' => $account->userName]
       );
   })
   

Integration Tips

• Multi-Panel Support: Register different providers per panel by reconfiguring SocialmentPlugin in each panel provider.
• Dynamic Visibility: Control button visibility with closures:

  ->visible(fn () => Auth::check() === false)
  

• Scoped Access: Request custom scopes (e.g., for Azure AD):

  ->registerProvider('azure', 'fab-microsoft', 'Azure AD', [
      'scopes' => ['User.Read', 'openid', 'profile'],
  ])
  

SPA Integration

For shared auth between Filament and SPA:

1. Add SPA routes:

   Route::spaAuth('dashboard');
   

2. Configure CORS and Sanctum:

   'paths' => ['spa/*'],
   'supports_credentials' => true,
   

3. Set environment variables for cookie sharing.

Gotchas and Tips

Pitfalls

1. Missing Styling: Forgetting to add @source in theme.css will hide provider buttons. Fix: Always include:

   @source '../../../../vendor/chrisreedio/socialment/resources';
   

2. Redirect URI Mismatch: Ensure redirect in config/services.php matches the callback URL pattern: https://yourdomain.com/login/{provider}/callback. Debug: Check .env for correct APP_URL and provider-specific URIs.

3. User Model Conflicts: Socialment expects a default User model. Override in config/socialment.php:

   'models' => [
       'user' => \App\Models\CustomUser::class,
   ],
   

4. Stateful Sessions: For SPA auth, ensure SESSION_DOMAIN starts with a dot (e.g., .localhost) and matches both frontend/backend domains.

Debugging

• Failed Logins: Check storage/logs/laravel.log for Socialite errors (e.g., invalid credentials). Common causes: Incorrect client_id/client_secret or missing scopes.

• Provider Buttons Missing: Verify:

  • Provider is registered in SocialmentPlugin.
  • Font Awesome icons are loaded (check theme.css).
  • No JavaScript errors in browser console.

Extension Points

1. Login Hooks: Use preLogin/postLogin to modify behavior:

   Socialment::preLogin(function (ConnectedAccount $account) {
       if ($account->provider === 'github' && !$account->user->isActive()) {
           throw new AbortedLoginException('Account suspended.');
       }
   });
   

2. Custom Views: Publish and override views:

   php artisan vendor:publish --tag="socialment-views"
   

   Modify resources/views/vendor/socialment/providers-list.blade.php for custom styling.

3. Provider-Specific Logic: Extend ConnectedAccount model or create provider-specific services to handle unique attributes (e.g., Azure AD groups).

Configuration Quirks

• Scopes: Some providers (e.g., Azure AD) require specific scopes. Always validate provider documentation.
• Stateful Domains: For SPA auth, ensure SANCTUM_STATEFUL_DOMAINS includes both frontend and backend URLs.
• Environment Variables: Use php artisan config:clear after updating .env for Socialite credentials.

Performance Tips

• Lazy Loading: Socialment buttons are lazy-loaded by default. For large panels, consider preloading critical assets.
• Caching: Cache provider configurations if using dynamic panels (e.g., in a multi-tenant app).