Social Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require akuma/social-bundle
   

   Enable in AppKernel.php:

   new Akuma\SocialBundle\AkumaSocialBundle(),
   

2. Configure Credentials Update parameters.yml with your Facebook/Google/Microsoft app credentials:

   facebook_id: "your_facebook_app_id"
   facebook_secret: "your_facebook_app_secret"
   google_id: "your_google_client_id"
   google_secret: "your_google_client_secret"
   

3. Update config.yml Reference the parameters:

   akuma_social:
       facebook:
           app_id: %facebook_id%
           app_secret: %facebook_secret%
           app_scopes: [email, public_profile]
       google:
           app_id: %google_id%
           app_secret: %google_secret%
           app_scopes: [email]
   

4. Register Routing Include in routing.yml:

   akuma_social:
       resource: "@AkumaSocialBundle/Resources/config/routing-all.yml"
       prefix: /
   

5. First Use Case: Facebook Login Add a button in your template:

   <a href="{{ path('akuma_social_facebook_login') }}">Login with Facebook</a>
   

   Redirects to /facebook/connect (auto-configured).

Implementation Patterns

Workflow: Social Authentication

1. User Clicks "Login with X" Redirects to /[provider]/connect (e.g., /facebook/connect). Bundle handles OAuth2 flow internally.

2. Post-Authentication

   • If user exists (via fos_userbundle), logs them in.
   • If new, creates a user with social profile data (email, name, etc.).
   • Redirects to default_target_path (configurable in security.yml).

3. Custom User Data Handling Override AkumaSocialBundle:User:SocialUserListener to extend user creation:

   // src/AkumaSocialBundle/EventListener/SocialUserListener.php
   public function onSocialAuthSuccess(SocialAuthSuccessEvent $event) {
       $user = $event->getUser();
       $user->setCustomField($event->getProvider()); // Example
   }
   

Integration Tips

• FOSUserBundle Compatibility Ensure FOS\UserBundle is installed and configured. The bundle extends its user provider.

  # security.yml
  providers:
      akuma_social_facebook:
          id: akuma_social.user_provider.facebook
  

• Custom Scopes Extend scopes in config.yml:

  akuma_social:
      facebook:
          app_scopes: [email, public_profile, user_birthday]
  

• Post-Auth Redirects Override default_target_path per provider in security.yml:

  akuma_social_facebook:
      default_target_path: /dashboard
  

• Microsoft-Specific Setup Ensure redirect URIs in Microsoft Dev Portal match:

  https://yourdomain.com/microsoft/connect
  

Gotchas and Tips

Pitfalls

1. Redirect URI Mismatches

   • Facebook/Google: Must match Allowed Domains in their dev consoles.
   • Microsoft: Defaults to /[provider]/connect (e.g., /microsoft/connect).
   • Fix: Update security.yml check_path if custom routes are used.

2. FOSUserBundle Conflicts

   • If User entity differs from FOS\UserBundle, override the provider:

     // src/AkumaSocialBundle/DependencyInjection/AkumaSocialExtension.php
     $provider = new \Akuma\SocialBundle\Security\User\SocialUserProvider(
         $container->get('fos_user.user_manager'),
         'Akuma\SocialBundle\Entity\User' // Your custom user class
     );
     

3. Scope Permissions

   • Facebook: public_profile requires app review for production.
   • Google: Enable "Google+ API" in the console.

4. State Parameter Issues

   • If using CSRF protection, ensure the bundle’s state handling aligns with your setup. Override AkumaSocialBundle:Security:Authenticator if needed.

Debugging

• OAuth Errors Check league/oauth2-client logs for token failures. Common causes:

  • Invalid client_id/client_secret.
  • Missing scopes or permissions.
  • Redirect URI mismatch.

• User Not Created Verify fos_user.user_manager is properly configured and the bundle’s listener is subscribed:

  // config.yml
  services:
      akuma_social.user_listener:
          class: Akuma\SocialBundle\EventListener\SocialUserListener
          tags:
              - { name: kernel.event_listener, event: akuma.social.auth.success, method: onSocialAuthSuccess }
  

Extension Points

1. Custom Providers Extend the bundle by creating a new provider class:

   // src/AkumaSocialBundle/Security/Provider/TwitterProvider.php
   class TwitterProvider extends AbstractSocialProvider {
       protected $providerName = 'twitter';
       // Implement OAuth2 logic for Twitter
   }
   

   Register in services.yml and update security.yml.

2. Post-Auth Events Listen for akuma.social.auth.success to modify user data:

   $event->getUser()->setLastSocialLogin(new \DateTime());
   

3. Template Overrides Override Twig templates in Resources/views/AkumaSocialBundle/ to customize login buttons or error messages.

4. Configuration Validation Add validation to parameters.yml to catch misconfigurations early:

   # app/config/validation.yml
   Akuma\SocialBundle\Validator\Constraints\ValidSocialConfig:
       parameters:
           facebook_id: "Not blank"
           google_id: "Not blank"