Hybridauth Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to composer.json:

   "azine/hybridauth-bundle": "dev-master"
   

   Run:

   composer update
   

2. Register the Bundle In config/bundles.php (Symfony 4+) or AppKernel.php:

   Azine\HybridAuthBundle\AzineHybridAuthBundle::class => ['all' => true],
   

3. Enable Routes In config/routes.yaml:

   azine_hybrid_auth:
       resource: "@AzineHybridAuthBundle/Resources/config/routing.yml"
       prefix: /hybrid-auth/
   

4. Configure a Provider In config/packages/azine_hybrid_auth.yaml:

   azine_hybrid_auth:
       debug: true
       providers:
           linkedin:
               enabled: true
               keys:
                   key: "%env(LINKEDIN_API_KEY)%"
                   secret: "%env(LINKEDIN_API_SECRET)%"
               scope: "r_basicprofile"
   

5. First Use Case: Authenticate with LinkedIn Create a controller to trigger authentication:

   use Azine\HybridAuthBundle\Controller\HybridAuthController;
   
   class AuthController extends AbstractController
   {
       public function login(HybridAuthController $hybridAuth)
       {
           return $hybridAuth->authenticate('linkedin');
       }
   }
   

   Add a route:

   app_login:
       path: /login/linkedin
       controller: App\Controller\AuthController::login
   

Implementation Patterns

Workflow: OAuth Flow Integration

1. Trigger Authentication Redirect users to the provider via the bundle’s endpoint:

   $hybridAuth->authenticate('linkedin'); // Redirects to LinkedIn OAuth
   

2. Handle Callback The bundle automatically handles the OAuth callback at /hybrid-auth/endpoint. Configure a listener to process the response:

   // src/EventListener/HybridAuthListener.php
   use Azine\HybridAuthBundle\Event\HybridAuthEvent;
   
   class HybridAuthListener
   {
       public function onAuthSuccess(HybridAuthEvent $event)
       {
           $userProfile = $event->getUserProfile();
           // Store user data in your DB or session
       }
   }
   

   Register the listener in config/services.yaml:

   services:
       App\EventListener\HybridAuthListener:
           tags:
               - { name: kernel.event_listener, event: azine.hybrid_auth.success, method: onAuthSuccess }
   

3. Access User Data After authentication, retrieve profile data:

   $userProfile = $hybridAuth->getUserProfile('linkedin');
   $email = $userProfile->email;
   $name = $userProfile->displayName;
   

Integration Tips

• Session Storage Enable persistent sessions in config/packages/azine_hybrid_auth.yaml:

  azine_hybrid_auth:
      store_for_user: true
  

  Run migrations:

  php bin/console doctrine:migrations:diff
  php bin/console doctrine:migrations:migrate
  

• Custom Providers For providers in additional-providers, configure the wrapper path:

  providers:
      xing:
          enabled: true
          wrapper:
              path: "%kernel.project_dir%/vendor/hybridauth/additional-providers/Xing/Xing.php"
          keys:
              key: "%env(XING_API_KEY)%"
              secret: "%env(XING_API_SECRET)%"
  

• LinkedIn-Specific Features Use the AzineMergedBusinessNetworksProvider service:

  $contacts = $this->get('azine.hybrid_auth.linkedin_contacts')->getContactProfiles();
  

Gotchas and Tips

Pitfalls

1. LinkedIn API Restrictions

   • Requires LinkedIn Partner Program approval for getLinkedInContacts().
   • Scope r_network is deprecated; use r_emailaddress or r_contactinfo instead.
   • Fix: Update scopes in config/packages/azine_hybrid_auth.yaml:

     scope: "r_basicprofile,r_emailaddress"
     

2. Debugging

   • Enable debug mode to log errors:

     azine_hybrid_auth:
         debug: true
     

   • Check logs at %kernel.logs_dir%/hybrid_auth_%kernel.environment%.log.

3. Session Expiry

   • HybridAuth sessions expire after ~2 hours. Refresh tokens if needed:

     $hybridAuth->refreshToken('linkedin');
     

4. Provider Configuration

   • Error: Class not found for custom providers.
   • Fix: Ensure the wrapper.path in config points to the correct file (e.g., vendor/hybridauth/additional-providers/Xing/Xing.php).

Debugging Tips

• Token Validation If OAuth fails, validate tokens manually:

  $hybridAuth->getHybridAuth()->debugMode = true;
  $hybridAuth->getHybridAuth()->debugFile = '/tmp/hybridauth.log';
  

• Environment Variables Use .env for API keys:

  LINKEDIN_API_KEY=your_key_here
  LINKEDIN_API_SECRET=your_secret_here
  

  Reference in config/packages/azine_hybrid_auth.yaml:

  keys:
      key: "%env(LINKEDIN_API_KEY)%"
  

Extension Points

1. Custom User Entity Extend the bundle’s HybridAuthUser entity:

   // src/Entity/HybridAuthUser.php
   use Azine\HybridAuthBundle\Entity\HybridAuthUser as BaseHybridAuthUser;
   
   class HybridAuthUser extends BaseHybridAuthUser
   {
       /**
        * @ORM\Column(type="string", nullable=true)
        */
       private $company;
   }
   

   Update the bundle’s UserProvider to map LinkedIn fields:

   $user->setCompany($userProfile->customProfile['industry']);
   

2. Event-Driven Extensions Listen to azine.hybrid_auth.failure for error handling:

   public function onAuthFailure(HybridAuthEvent $event)
   {
       $error = $event->getException()->getMessage();
       // Log or notify user
   }
   

3. Caching Strategies Cache LinkedIn contacts to reduce API calls:

   $cache = $this->get('cache.app');
   $contacts = $cache->get('linkedin_contacts_' . $userId, function() use ($userId) {
       return $this->get('azine.hybrid_auth.linkedin_contacts')->getContactProfiles();
   });