Xxllnc Zgw Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require common-gateway/xxllnc-zgw-bundle
   

   Ensure CommonGateway/CoreBundle and CommonGateway/ZGWBundle are also installed (they are auto-installed as dependencies).

2. Enable the Bundle Add to config/bundles.php:

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

3. Configure Services Publish the default config:

   php bin/console common-gateway:install --env=prod
   

   Edit config/packages/xxllnc_zgw.yaml to define:

   • xxllnc_api_endpoint
   • zgw_api_endpoint
   • sync_interval (e.g., PT1H for hourly syncs)
   • mapping_rules (see Implementation Patterns).

4. First Use Case: Sync a Zaak (Case) Trigger a manual sync via CLI:

   php bin/console xxllnc:zgw:sync --zaak-id=12345
   

   Verify logs in var/log/dev.log for mapping results.

Implementation Patterns

Core Workflows

1. Bidirectional Sync

   • XXLNC → ZGW: Use ZaakSyncCommand to push XXLNC cases to ZGW:

     # config/packages/xxllnc_zgw.yaml
     xxllnc_zgw:
         sync:
             zaak:
                 enabled: true
                 direction: "xxllnc_to_zgw"
     

   • ZGW → XXLNC: Configure pull syncs via cron (e.g., * * * * * php bin/console xxllnc:zgw:sync --direction=zgw_to_xxllnc).

2. Mapping Custom Fields Extend default mappings in a custom service:

   # config/services.yaml
   services:
       App\Service\CustomZGWMapper:
           arguments:
               $xxllncMapper: '@xxllnc_zgw.mapper.zaak'
   

   // src/Service/CustomZGWMapper.php
   class CustomZGWMapper implements MapperInterface {
       public function mapToXXLNC(array $zgwData): array {
           $zgwData['custom_field'] = $this->xxllncMapper->mapCustomField($zgwData);
           return $this->xxllncMapper->mapToXXLNC($zgwData);
       }
   }
   

3. Event-Driven Syncs Listen for ZGW events (e.g., zaak.updated) and trigger syncs:

   // src/EventListener/ZGWZaakListener.php
   class ZGWZaakListener {
       public function onZaakUpdated(ZaakEvent $event) {
           $this->container->get('xxllnc_zgw.sync.zaak')->sync($event->getZaak());
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\ZGWZaakListener:
           tags:
               - { name: kernel.event_listener, event: zaak.updated, method: onZaakUpdated }
   

4. Batch Processing Use the BatchSyncCommand for large datasets:

   php bin/console xxllnc:zgw:batch-sync --limit=100 --offset=0
   

Integration Tips

• API Rate Limiting: Configure retries in xxllnc_zgw.yaml:

  xxllnc_zgw:
      client:
          retry_attempts: 3
          delay: 1000 # ms
  

• Logging: Enable debug mode for sync details:

  xxllnc_zgw:
      debug: true
  

• Testing: Use the SyncTestCase base class:

  use CommonGateway\XxllncZGWBundle\Test\SyncTestCase;
  
  class MySyncTest extends SyncTestCase {
      public function testZaakSync() {
          $this->assertSyncSuccess('zaak', ['id' => 123]);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Schema Mismatches

   • Issue: XXLNC and ZGW schemas may diverge (e.g., zaaktype vs. type).
   • Fix: Override mappings in config/packages/xxllnc_zgw.yaml:

     xxllnc_zgw:
         mapping:
             zaak:
                 fields:
                     zaaktype: type
     

   • Debug: Use php bin/console debug:container xxllnc_zgw.mapper.zaak to inspect the mapper.

2. Circular References

   • Issue: Syncing a Zaak may trigger syncs for linked ZaakType or Rol, causing infinite loops.
   • Fix: Disable circular syncs in config:

     xxllnc_zgw:
         sync:
             zaak:
                 ignore_related: true
     

3. Authentication Failures

   • Issue: API tokens may expire silently.
   • Fix: Implement a TokenRefreshListener:

     class TokenRefreshListener {
         public function onAuthFailure(AuthEvent $event) {
             $this->refreshToken();
             $event->setToken($this->getRefreshedToken());
         }
     }
     

4. Idempotency

   • Issue: Duplicate syncs may create redundant records.
   • Fix: Use sync_token in payloads:

     xxllnc_zgw:
         sync:
             zaak:
                 idempotency_key: "zaak_id"
     

Debugging Tips

• Enable SQL Logging:

  php bin/console debug:config doctrine | grep logging
  

  Set logging: true in config/packages/doctrine.yaml.

• Dump Mapped Data:

  $mapper = $this->container->get('xxllnc_zgw.mapper.zaak');
  dump($mapper->mapToXXLNC($zgwData));
  

• Check Sync Status:

  php bin/console xxllnc:zgw:status
  

Extension Points

1. Custom Sync Strategies Extend AbstractSyncStrategy:

   class CustomZaakSyncStrategy extends AbstractSyncStrategy {
       protected function getSyncQuery() {
           return $this->entityManager->createQuery(
               'SELECT z FROM App\Entity\Zaak z WHERE z.customFlag = true'
           );
       }
   }
   

   Register in services.yaml:

   services:
       App\Sync\CustomZaakSyncStrategy:
           tags:
               - { name: xxllnc_zgw.sync_strategy, type: zaak }
   

2. Webhook Integration Use the WebhookReceiver to trigger syncs:

   $receiver = new WebhookReceiver($this->container->get('xxllnc_zgw.client'));
   $receiver->handleRequest($request); // Triggers sync on POST /webhook/zaak
   

3. Async Processing Offload syncs to a queue (e.g., Symfony Messenger):

   xxllnc_zgw:
       sync:
           zaak:
               async: true
   

   Requires symfony/messenger and a queue worker (e.g., RabbitMQ).