Grand Id Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require develit-ab/grand-id-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       DevelitAB\GrandIDBundle\GrandIDBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console grandid:install
   

   Update config/packages/grandid.yaml with your Grand ID API credentials:

   grandid:
       api_key: '%env(GRANDID_API_KEY)%'
       mock_mode: false # Set to true for testing
   

3. First Use Case Authenticate a user via Grand ID:

   use DevelitAB\GrandIDBundle\Service\GrandIDService;
   
   class AuthController extends AbstractController
   {
       public function login(GrandIDService $grandid): Response
       {
           $session = $grandid->authenticate('user@example.com', 'password123');
           // Handle session response
       }
   }
   

Implementation Patterns

Core Workflows

1. Authentication Flow

   • Use GrandIDService to handle login/logout:

     $session = $grandid->authenticate($email, $password);
     $grandid->logout($sessionId);
     

   • For OAuth flows, use authorize() and exchangeCode() methods.

2. Session Management

   • Fetch user data:

     $userData = $grandid->getUserData($sessionId);
     

   • Update user attributes:

     $grandid->updateUser($sessionId, ['custom_field' => 'value']);
     

3. Mock Mode for Testing

   • Enable mock_mode: true in config to bypass API calls.
   • Use GrandIDService::mockAuthenticate() to simulate sessions in DB.

Integration Tips

• Event Listeners Bind to grandid.session.created or grandid.session.updated events for post-auth hooks:

  # config/services.yaml
  services:
      App\EventListener\GrandIDListener:
          tags:
              - { name: kernel.event_listener, event: grandid.session.created, method: onSessionCreated }
  

• Twig Integration Pass the service to templates:

  {% if grandid.isAuthenticated(sessionId) %}
      Welcome, {{ grandid.getUserData(sessionId).name }}
  {% endif %}
  

• Database Schema The bundle auto-creates a grandid_sessions table. Customize via migrations if needed.

Gotchas and Tips

Common Pitfalls

1. API Key Misconfiguration

   • Ensure GRANDID_API_KEY is set in .env and matches the config.
   • Debug with mock_mode: true to isolate issues.

2. Session Expiry

   • Grand ID sessions expire after 30 minutes by default. Use refreshSession() to extend:

     $grandid->refreshSession($sessionId);
     

3. Mock Mode Quirks

   • Mock sessions do not trigger real API callbacks (e.g., webhooks).
   • Reset mock data with:

     php bin/console doctrine:fixtures:load --append --env=test
     

Debugging Tips

• Enable Verbose Logging Add to config/packages/grandid.yaml:

  grandid:
      debug: true
  

  Logs appear in var/log/dev.log.

• API Response Inspection Use GrandIDService::getLastResponse() to debug raw API calls:

  $response = $grandid->authenticate($email, $password);
  error_log($grandid->getLastResponse());
  

Extension Points

1. Custom Session Storage Override the default Doctrine repository by binding your own:

   # config/services.yaml
   services:
       App\Repository\CustomGrandIDSessionRepository:
           arguments:
               - '@doctrine.orm.entity_manager'
           tags: ['grandid.session_repository']
   

2. Webhook Handling Extend GrandIDWebhookEvent to process custom payloads:

   class CustomWebhookSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'grandid.webhook.received' => 'onWebhookReceived',
           ];
       }
   }
   

3. Rate Limiting Implement a decorator for API rate limits:

   $grandid->setRateLimiter(new CustomRateLimiter());