Zgw To Open Belasting Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the bundle to your Symfony project via Composer:

   composer require common-gateway/zgw-to-open-belasting-bundle
   

   Enable the bundle in config/bundles.php:

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

2. Configuration Publish the default configuration:

   php bin/console config:dump-reference CommonGateway\ZgwToOpenBelastingBundle
   

   Configure the bundle in config/packages/zgw_to_open_belasting.yaml:

   zgw_to_open_belasting:
       api_client: '%env(OPEN_BELASTINGEN_API_URL)%'
       api_token: '%env(OPEN_BELASTINGEN_API_TOKEN)%'
       zgw_client: '@zgw_client' # Your ZGW client service ID
   

3. First Use Case: Transform a ZGW Case to Open Belasting Use the transformer service to convert a ZGW case to an Open Belasting API payload:

   use CommonGateway\ZgwToOpenBelastingBundle\Service\ZgwToOpenBelastingTransformer;
   
   class MyController extends AbstractController
   {
       public function transformZGWCase(ZgwToOpenBelastingTransformer $transformer, ZGWCase $zgwCase): JsonResponse
       {
           $openBelastingPayload = $transformer->transformCase($zgwCase);
           return $this->json($openBelastingPayload);
       }
   }
   

Implementation Patterns

Core Workflows

1. Case Transformation

   • Use ZgwToOpenBelastingTransformer to convert ZGW cases (e.g., ZGWCase, ZGWObjection) into Open Belasting API-compatible payloads.
   • Example for objections:

     $objectionPayload = $transformer->transformObjection($zgwObjection);
     

2. API Integration

   • Leverage the OpenBelastingApiClient service to send transformed data to the Open Belasting API:

     $client = $this->container->get('zgw_to_open_belasting.api_client');
     $response = $client->createAssessment($payload);
     

3. Event-Driven Processing

   • Subscribe to ZGW events (e.g., ZGWCaseCreatedEvent) and trigger transformations automatically:

     // In a listener
     public function onCaseCreated(ZGWCaseCreatedEvent $event)
     {
         $transformer = $this->container->get(ZgwToOpenBelastingTransformer::class);
         $payload = $transformer->transformCase($event->getCase());
         $this->openBelastingApiClient->createAssessment($payload);
     }
     

Integration Tips

• Schema Validation: Use the bundle’s built-in schema validators to ensure ZGW data matches Open Belasting requirements before transformation.
• Custom Mappings: Extend the default mappings by overriding the ZgwToOpenBelastingTransformer service:

  # config/services.yaml
  services:
      App\Service\CustomZgwToOpenBelastingTransformer:
          decorates: 'zgw_to_open_belasting.transformer'
          arguments: ['@.inner']
  

• Batch Processing: Process multiple ZGW cases in bulk using the BatchTransformer:

  $batchPayloads = $transformer->transformBatch($zgwCases);
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • The Open Belasting API may throttle requests. Implement retry logic with exponential backoff in your OpenBelastingApiClient calls.
   • Example:

     use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
     use Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface;
     use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
     
     try {
         $response = $client->request('POST', '/assessments', [
             'json' => $payload,
         ]);
     } catch (TransportExceptionInterface $e) {
         // Retry logic here
     }
     

2. Schema Mismatches

   • ZGW cases may not always map cleanly to Open Belasting schemas. Use the SchemaValidator to catch issues early:

     $validator = $this->container->get('zgw_to_open_belasting.schema_validator');
     $errors = $validator->validateCase($zgwCase);
     if (!empty($errors)) {
         throw new \RuntimeException('Invalid ZGW case for Open Belasting: ' . implode(', ', $errors));
     }
     

3. Token Expiry

   • The Open Belasting API token may expire. Handle 401 Unauthorized responses by refreshing the token or reconfiguring the client.

Debugging Tips

• Enable Debug Mode: Set debug: true in the bundle config to log detailed transformation steps:

  zgw_to_open_belasting:
      debug: true
  

• Log Payloads: Log transformed payloads before sending to the API for verification:

  $this->logger->info('Open Belasting payload', ['payload' => $payload]);
  

Extension Points

1. Custom Transformers

   • Override the default transformer for specific ZGW types by implementing ZgwToOpenBelastingTransformerInterface:

     class CustomObjectionTransformer implements ZgwToOpenBelastingTransformerInterface
     {
         public function transform($zgwData): array
         {
             // Custom logic
             return $mappedData;
         }
     }
     

   • Register it as a service and tag it with zgw_to_open_belasting.transformer.

2. Additional API Endpoints

   • Extend the OpenBelastingApiClient to support custom endpoints:

     class ExtendedApiClient extends OpenBelastingApiClient
     {
         public function customEndpoint(array $data): ResponseInterface
         {
             return $this->client->request('POST', '/custom', ['json' => $data]);
         }
     }
     

   • Override the service in config/services.yaml.

3. Event Listeners

   • Listen for ZgwToOpenBelastingTransformedEvent to intercept or modify transformed data:

     public static function getSubscribedEvents()
     {
         return [
             ZgwToOpenBelastingTransformedEvent::class => 'onTransformed',
         ];
     }
     
     public function onTransformed(ZgwToOpenBelastingTransformedEvent $event)
     {
         $event->setPayload($this->modifyPayload($event->getPayload()));
     }