Soluti Bird Id Symfony Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require cm2tech/soluti-bird-id-symfony-bundle
   

   Ensure your config/packages/soluti_bird_id.yaml is properly configured (if auto-generated, verify credentials).

2. First Use Case: Fetching a Client Token

   use Soluti\BirdIdSymfonyBundle\Service\OauthService;
   use Soluti\BirdIdSymfonyBundle\Request\ClientToken;
   
   $request = new ClientToken('CLIENT_ID', 'CLIENT_SECRET');
   $response = OauthService::clientToken($request);
   
   // Parse response (e.g., JSON)
   $data = json_decode($response->getContent(false), true);
   

3. Where to Look First

   • Service Class: src/Service/OauthService.php (core logic for API calls).
   • Request Classes: src/Request/ (e.g., ClientToken.php for payloads).
   • Config: config/packages/soluti_bird_id.yaml (credentials, endpoints).

Implementation Patterns

Workflows

1. OAuth Token Flow

   • Use ClientToken for initial token acquisition (e.g., in a LoginController or AuthService).
   • Cache tokens (e.g., with Symfony’s CacheInterface) to avoid repeated requests.

   // Example: Cached token retrieval
   $cache = $this->get('cache.app');
   $token = $cache->get('bird_id_token');
   if (!$token) {
       $token = OauthService::clientToken(new ClientToken($clientId, $clientSecret));
       $cache->set('bird_id_token', $token, 3500); // 1h TTL
   }
   

2. API Integration

   • Attach tokens to requests via a HTTP Client Interceptor (e.g., Symfony’s HttpClient middleware).
   • Example:

     $client = $this->get('http_client');
     $client->setDefaultOptions([
         'headers' => [
             'Authorization' => 'Bearer ' . $token->getContent(),
         ],
     ]);
     

3. Event-Driven Patterns

   • Extend the bundle by listening to kernel events (e.g., KernelEvents::REQUEST) to inject BirdID logic dynamically.

Integration Tips

• Dependency Injection: Prefer injecting OauthService via constructor for testability.

  public function __construct(private OauthService $oauthService) {}
  

• Environment Variables: Store CLIENT_ID/CLIENT_SECRET in .env (e.g., BIRD_ID_CLIENT_ID).
• Error Handling: Wrap API calls in try-catch blocks to handle ClientException/ServerException.

  try {
      $response = $this->oauthService->clientToken($request);
  } catch (\Exception $e) {
      $this->logger->error('BirdID API failed: ' . $e->getMessage());
      throw new \RuntimeException('BirdID service unavailable');
  }
  

Gotchas and Tips

Pitfalls

1. Hardcoded Endpoints

   • The bundle uses fixed BirdID endpoints (api.birdid.com.br). Override via config if testing locally:

     # config/packages/soluti_bird_id.yaml
     soluti_bird_id:
         endpoints:
             oauth_application: 'http://localhost:8000/oauth/application'
     

2. Token Expiry

   • BirdID tokens expire (typically 1h). Implement a refresh mechanism or retry logic:

     if ($response->getStatusCode() === 401) {
         $token = OauthService::clientToken(new ClientToken(...));
         // Retry request with new token
     }
     

3. No Symfony HTTP Client Integration

   • The bundle lacks built-in HTTP client integration. Manually attach tokens to requests or create a decorator.

4. Limited Request Types

   • Only ClientToken is exposed. For other endpoints (e.g., /v0/oauth/application), extend OauthService:

     // src/Service/OauthService.php (extend)
     public static function applicationToken(ApplicationRequest $request) { ... }
     

Debugging

• Enable Debug Mode: Set APP_DEBUG=true in .env to see raw API responses.
• Log Responses: Use Symfony’s Monolog to log payloads:

  $this->logger->debug('BirdID Response', ['status' => $response->getStatusCode(), 'body' => $response->getContent()]);
  

Extension Points

1. Custom Requests

   • Extend Request\AbstractRequest to support additional BirdID endpoints:

     class CustomRequest extends AbstractRequest {
         public function __construct(string $customParam) { ... }
     }
     

2. Response Decorators

   • Decorate OauthService to transform responses (e.g., auto-parse JSON):

     class DecoratedOauthService implements OauthServiceInterface {
         public function clientToken(ClientToken $request): ResponseInterface {
             $response = $this->decorated->clientToken($request);
             return new JsonResponse(json_decode($response->getContent(), true));
         }
     }
     

3. Event Listeners

   • Trigger events before/after API calls (e.g., for analytics):

     // src/EventListener/BirdIdListener.php
     public function onKernelRequest(GetResponseEvent $event) {
         if ($event->isMasterRequest()) {
             $token = OauthService::clientToken(...);
             // Attach to request
         }
     }