Chat Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require banckle/chat-sdk-php banckle/chat-bundle
   

   Add the bundle to AppKernel.php:

   new Banckle\ChatBundle\BanckleChatBundle(),
   

2. Configuration: Add to config.yml:

   banckle_chat:
       apiKey: "YOUR_API_KEY"
       banckleAccountUri: "https://apps.banckle.com/api/v2"
       banckleChatUri: "https://chat.banckle.com/v3"
   

3. First Use Case: Generate a token for authentication:

   $banckleChat = $this->get('bancklechat.api');
   $token = $banckleChat->getToken('user@example.com', 'password');
   

Where to Look First

• Service Container: The bundle exposes bancklechat.api as a service.
• SDK Documentation: Refer to Banckle.Chat SDK for API endpoints and methods.
• Config Reference: Check BanckleChatBundle/Resources/config/services.yml for service definitions.

Implementation Patterns

Workflows

1. Authentication Flow:

   // Generate token
   $token = $this->get('bancklechat.api')->getToken($email, $password);
   
   // Create API instance (e.g., DepartmentsApi)
   $departmentsApi = $this->get('bancklechat.api')->createInstance('DepartmentsApi', $token);
   
   // Fetch data
   $departments = $departmentsApi->getDepartments();
   

2. Dependency Injection: Inject the service directly into controllers/services:

   use Banckle\ChatBundle\Service\BanckleChatService;
   
   class ChatController {
       public function __construct(private BanckleChatService $banckleChat) {}
   
       public function index() {
           $token = $this->banckleChat->getToken('user@example.com', 'password');
           // ...
       }
   }
   

3. Token Management: Cache tokens to avoid repeated authentication (e.g., using Symfony’s cache system):

   $cache = $this->get('bancklechat.cache');
   $token = $cache->get('banckle_token') ?: $this->get('bancklechat.api')->getToken($email, $password);
   $cache->set('banckle_token', $token, 3600); // Cache for 1 hour
   

Integration Tips

• Event Listeners: Extend functionality by listening to Banckle events (e.g., token expiration):

  # config.yml
  services:
      app.banckle_token_listener:
          class: AppBundle\EventListener\BanckleTokenListener
          tags:
              - { name: kernel.event_listener, event: banckle.token.expired, method: onTokenExpired }
  

• Custom API Clients: Extend the base SDK client for reusable logic:

  class CustomChatClient extends \Banckle\Chat\Api\ApiClient {
      public function fetchUserConversations($token, $userId) {
          $conversationsApi = $this->createInstance('ConversationsApi', $token);
          return $conversationsApi->getConversations($userId);
      }
  }
  

• Symfony Forms: Bind Banckle data to forms for user input (e.g., department selection):

  $form = $this->createFormBuilder()
      ->add('department', EntityType::class, [
          'class' => 'AppBundle\Entity\Department',
          'choices' => $this->getDepartmentsFromBanckle($token),
      ])
      ->getForm();
  

Gotchas and Tips

Pitfalls

1. Token Expiration:

   • Tokens may expire silently. Implement retry logic or event listeners for banckle.token.expired.
   • Example:

     try {
         $result = $api->getDepartments($token);
     } catch (\Banckle\Chat\Exception\UnauthorizedException $e) {
         $token = $this->refreshToken(); // Custom method
         return $api->getDepartments($token);
     }
     

2. Rate Limiting:

   • Banckle’s API may throttle requests. Use exponential backoff in retries:

     use Symfony\Component\Stopwatch\Stopwatch;
     
     $stopwatch = new Stopwatch();
     $event = $stopwatch->start('banckle_request');
     
     try {
         $result = $api->getData($token);
     } catch (\Banckle\Chat\Exception\RateLimitException $e) {
         $event->stop();
         $duration = $event->getDuration();
         sleep($duration * 2); // Exponential backoff
         retry;
     }
     

3. Configuration Overrides:

   • Avoid hardcoding apiKey or URIs. Use environment variables or parameter bags:

     # config/services.yaml
     parameters:
         banckle.api_key: '%env(BANCKLE_API_KEY)%'
     services:
         bancklechat.api:
             arguments:
                 $apiKey: '%banckle.api_key%'
     

Debugging

1. Enable SDK Debugging: Set the debug option in the SDK client to log requests/responses:

   $client = new \Banckle\Chat\Api\ApiClient(['debug' => true]);
   

2. Common Errors:

   • 401 Unauthorized: Verify apiKey and token generation.
   • 404 Not Found: Check banckleChatUri and endpoint paths (e.g., /v3/departments).
   • 500 Server Error: Banckle’s API may be down; implement circuit breakers.

Extension Points

1. Custom API Responses: Transform Banckle responses into domain objects:

   class BanckleResponseTransformer {
       public function transformDepartment(array $data): Department {
           return (new Department())
               ->setId($data['id'])
               ->setName($data['name']);
       }
   }
   

2. Middleware: Add request/response middleware to the SDK client:

   $client->setMiddleware(new class implements \Banckle\Chat\Api\Middleware {
       public function handle($request, \Closure $next) {
           $request->setHeader('X-Custom-Header', 'value');
           return $next($request);
       }
   });
   

3. Testing: Mock the Banckle service in tests:

   $this->container->set('bancklechat.api', $this->createMock(BanckleChatService::class));
   $mockApi->method('getToken')->willReturn('mock_token');