Abstract Social Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ailove-dev/abstract-social-bundle
   

   Add to config/bundles.php (Symfony) or config/app.php (Laravel via bridge):

   AiloveDev\AbstractSocialBundle\AbstractSocialBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="AiloveDev\AbstractSocialBundle\AbstractSocialBundle" --tag="config"
   

   Edit config/abstract_social.php to define supported providers (e.g., facebook, google).

3. First Use Case Inject the SocialManager into a controller/service:

   use AiloveDev\AbstractSocialBundle\Manager\SocialManager;
   
   public function __construct(private SocialManager $socialManager) {}
   
   public function handleLogin(Request $request) {
       $provider = $this->socialManager->getProvider('facebook');
       $user = $provider->getUser(); // Returns authenticated user data
       // Proceed with user registration/login
   }
   

Implementation Patterns

Core Workflows

1. Provider Integration

   • Define providers in config/abstract_social.php:

     'providers' => [
         'facebook' => [
             'client_id' => env('FACEBOOK_CLIENT_ID'),
             'client_secret' => env('FACEBOOK_SECRET'),
             'redirect_uri' => env('FACEBOOK_REDIRECT_URI'),
         ],
     ],
     

   • Use the SocialManager to dynamically fetch providers:

     $provider = $socialManager->getProvider('facebook');
     $authUrl = $provider->getAuthorizationUrl(); // Generate OAuth URL
     

2. User Data Handling

   • Fetch user data post-authentication:

     $userData = $provider->getUser();
     // Example output: ['id' => '123', 'name' => 'John Doe', 'email' => 'john@example.com']
     

   • Map to your user model:

     $user = User::firstOrCreate(
         ['email' => $userData['email']],
         ['name' => $userData['name']]
     );
     

3. Event Listeners

   • Listen for provider events (e.g., SocialAuthSuccess):

     // In EventServiceProvider
     protected $listen = [
         'AiloveDev\AbstractSocialBundle\Events\SocialAuthSuccess' => [
             'App\Listeners\HandleSocialLogin',
         ],
     ];
     

Advanced Patterns

• Custom Provider Abstraction Extend AiloveDev\AbstractSocialBundle\Provider\AbstractProvider for unsupported services:

  class TwitterProvider extends AbstractProvider {
      protected $name = 'twitter';
      // Override auth logic here
  }
  

  Register in config:

  'providers' => [
      'twitter' => \App\Providers\TwitterProvider::class,
  ],
  

• Stateful Authentication Use the SocialManager to store/validate state tokens:

  $state = $socialManager->generateState();
  // Store in session: session(['social_state' => $state])
  $provider->setState($state); // Validate on callback
  

Gotchas and Tips

Common Pitfalls

1. Provider Initialization

   • Issue: getProvider() returns null for undefined providers.
   • Fix: Ensure providers are listed in config/abstract_social.php and their dependencies (e.g., league/oauth2-server) are installed.

2. State Validation

   • Issue: CSRF attacks if state tokens aren’t validated.
   • Tip: Always use $provider->setState() and compare on callback:

     if ($provider->validateState(session('social_state'))) {
         // Proceed
     }
     

3. Configuration Overrides

   • Issue: Provider settings (e.g., scopes) may not persist.
   • Tip: Extend the provider class to override defaults:

     class CustomFacebookProvider extends FacebookProvider {
         protected $scopes = ['email', 'public_profile', 'user_friends'];
     }
     

Debugging Tips

• Enable Logging Add to config/abstract_social.php:

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

  Logs OAuth flows to storage/logs/abstract_social.log.

• Provider-Specific Errors

  • For OAuth failures, check the provider’s raw response:

    try {
        $user = $provider->getUser();
    } catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {
        \Log::error($e->getResponse()->getBody());
    }
    

Extension Points

1. Custom User Mappers Override mapUserData() in a provider to transform raw data:

   protected function mapUserData(array $data): array {
       return [
           'id' => $data['id'],
           'name' => $data['name'],
           'avatar' => $data['picture']['data']['url'],
       ];
   }
   

2. Post-Auth Hooks Dispatch events in your provider’s getUser() method:

   $user = $this->mapUserData($data);
   event(new SocialAuthSuccess($this->name, $user));
   

3. Rate Limiting Implement AiloveDev\AbstractSocialBundle\Contracts\RateLimitable for providers with API limits:

   class GitHubProvider extends AbstractProvider implements RateLimitable {
       public function isRateLimited(): bool {
           return $this->httpClient->getLastResponse()->getStatusCode() === 403;
       }
   }