Customer Interaction Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require common-gateway/customer-interaction-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       CommonGateway\CustomerInteractionBundle\CustomerInteractionBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference | grep customer_interaction
   

   Or manually configure in config/packages/common_gateway_customer_interaction.yaml:

   customer_interaction:
       api_client:
           endpoint: '%env(CUSTOMER_INTERACTION_API_URL)%'
           api_key: '%env(CUSTOMER_INTERACTION_API_KEY)%'
       default_party_type: 'burger'  # or 'organisatie'
   

3. First Use Case: Fetch a Party

   use CommonGateway\CustomerInteractionBundle\Service\PartyService;
   
   class MyController extends AbstractController
   {
       public function showParty(PartyService $partyService)
       {
           $party = $partyService->findByBsn('123456789');
           return $this->json($party);
       }
   }
   

Implementation Patterns

Core Workflows

1. Party Management

   • Fetching Parties:

     $partyService->findByBsn('123456789'); // For individuals
     $partyService->findByKvk('12345678');  // For organizations
     

   • Creating Parties:

     $party = $partyService->create([
         'type' => 'burger',
         'bsn' => '123456789',
         'name' => 'John Doe',
     ]);
     

2. Task Management

   • Create and Assign Tasks:

     $taskService->createTask([
         'title' => 'Process BSN request',
         'description' => 'Verify BSN details',
         'party_id' => $party->getId(),
         'assignee' => 'user@example.com', // Employee email
         'due_date' => new \DateTime('+7 days'),
     ]);
     

   • Update Task Status:

     $taskService->updateStatus($taskId, 'in_uitvoering');
     

3. Message Handling

   • Send a Message:

     $messageService->sendMessage([
         'party_id' => $party->getId(),
         'subject' => 'Your request update',
         'content' => 'Your request is being processed...',
         'channel' => 'email', // or 'sms', 'letter'
     ]);
     

Integration Tips

1. Event Listeners Subscribe to party/task events for real-time updates:

   // src/EventListener/CustomerInteractionListener.php
   class CustomerInteractionListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               PartyEvents::PARTY_CREATED => 'onPartyCreated',
               TaskEvents::TASK_STATUS_UPDATED => 'onTaskStatusUpdated',
           ];
       }
   
       public function onPartyCreated(PartyCreatedEvent $event)
       {
           // Log or trigger follow-up actions
       }
   }
   

2. API Client Customization Extend the default API client for custom logic:

   // config/packages/common_gateway_customer_interaction.yaml
   customer_interaction:
       api_client:
           custom_headers:
               X-Custom-Header: 'value'
           middleware: ['custom.middleware']
   

3. Form Integration Use Symfony Forms to bind party/task data:

   $builder->add('party', EntityType::class, [
       'class' => Party::class,
       'choice_label' => 'name',
       'label' => 'Select Party',
   ]);
   

Gotchas and Tips

Common Pitfalls

1. API Rate Limiting

   • The bundle respects API rate limits. Handle RateLimitExceededException:

     try {
         $partyService->findByBsn('123456789');
     } catch (RateLimitExceededException $e) {
         $this->addFlash('error', 'API rate limit exceeded. Retry later.');
         return $this->redirectToRoute('home');
     }
     

2. Party Type Mismatch

   • Ensure default_party_type in config matches your use case (burger or organisatie). Mixing types may cause validation errors.

3. Idempotency in Task Updates

   • Use idempotency_key when updating tasks to avoid duplicate operations:

     $taskService->updateStatus($taskId, 'in_uitvoering', [
         'idempotency_key' => uniqid(),
     ]);
     

Debugging Tips

1. Enable API Debugging

   # config/packages/common_gateway_customer_interaction.yaml
   customer_interaction:
       api_client:
           debug: true
   

   Logs will appear in var/log/dev.log.

2. Validate API Responses Use the OpenAPI docs (link) to verify response schemas. Example:

   $response = $partyService->findByBsn('123456789');
   if (!$response->isValid()) {
       dd($response->getErrors()); // Debug validation errors
   }
   

3. Handle Deprecated Fields Some fields (e.g., klant_id) may be deprecated. Use partyService->getLegacyData() to access old formats:

   $legacyData = $partyService->getLegacyData($party);
   

Extension Points

1. Custom Party Attributes Extend the Party entity:

   // src/Entity/CustomParty.php
   class CustomParty extends Party
   {
       #[ORM\Column(type: 'string', nullable: true)]
       private $customAttribute;
   
       // Add getters/setters
   }
   

   Register in services.yaml:

   services:
       CommonGateway\CustomerInteractionBundle\Entity\Party:
           alias: App\Entity\CustomParty
   

2. Override API Client Replace the default client for full control:

   # config/packages/common_gateway_customer_interaction.yaml
   customer_interaction:
       api_client: App\Service\CustomApiClient
   

3. Add Custom Actions Extend the ActionService:

   class CustomActionService extends ActionService
   {
       public function customAction(Party $party, array $data)
       {
           // Custom logic
           return $this->apiClient->post('/custom-endpoint', $data);
       }
   }
   

   Bind in services.yaml:

   services:
       App\Service\CustomActionService:
           decorates: 'common_gateway.customer_interaction.action_service'
           arguments: ['@common_gateway.customer_interaction.action_service']