Vrijbrp To Zgw Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Prerequisites:

   • Ensure your Laravel/Symfony project is integrated with CommonGateway and CoreBundle.
   • Verify the common-gateway/vrijbrp-to-zgw-bundle is compatible with your ZGW (Zaken API Gateway) and VrijBRP (open-source BRP alternative) versions.

2. Installation:

   • Install via Composer:

     composer require common-gateway/vrijbrp-to-zgw-bundle:dev-main
     

   • Install schemas (required for ZGW integration):

     php artisan console commongateway:install common-gateway/vrijbrp-to-zgw-bundle
     

     (Note: If using Symfony, replace php artisan with php bin/console.)

3. First Use Case:

   • Navigate to the CommonGateway Admin UI (/admin/plugins) and locate the VrijBRPToZGWBundle plugin.
   • Enable and configure the plugin via the UI or manually in config/packages/common_gateway/vrijbrp_to_zgw.yaml.

Implementation Patterns

Core Workflows

1. Data Synchronization:

   • The bundle handles bidirectional synchronization between VrijBRP (a BRP-like system) and ZGW (Zaken API Gateway).
   • Use the CommonGateway Admin UI to trigger sync jobs or configure cron jobs for automated syncs:

     # config/packages/common_gateway/vrijbrp_to_zgw.yaml
     sync:
         cron: "0 3 * * *"  # Run daily at 3 AM
     

2. Event-Driven Integration:

   • Leverage CommonGateway’s event system to hook into VrijBRP/ZGW events (e.g., zgw.zaken.created, vrijbrp.person.updated).
   • Example listener in Laravel:

     use CommonGateway\VrijBRPToZGWBundle\Event\SyncEvent;
     
     public function handleSyncEvent(SyncEvent $event)
     {
         // Custom logic for post-sync processing
     }
     

     Register the listener in EventServiceProvider:

     protected $listen = [
         SyncEvent::class => [
             YourListener::class,
         ],
     ];
     

3. Schema Management:

   • The bundle auto-installs ZGW schemas. Extend or override schemas in:

     config/packages/common_gateway/schemas/
     

   • Example custom schema extension:

     # config/packages/common_gateway/schemas/zaken.yaml
     attributes:
         custom_field:
             type: string
             required: false
     

4. API Gateway Configuration:

   • Configure ZGW API endpoints in config/packages/common_gateway/zgw.yaml:

     zgw:
         base_uri: "https://api.zgw.example.com"
         api_key: "%env(ZGW_API_KEY)%"
     

5. Logging and Monitoring:

   • Enable debug logging in config/logging.php:

     'channels' => [
         'zgw_sync' => [
             'driver' => 'single',
             'path' => storage_path('logs/zgw_sync.log'),
             'level' => 'debug',
         ],
     ],
     

   • Monitor sync jobs via the CommonGateway Admin UI under Jobs > Sync Logs.

Gotchas and Tips

Pitfalls

1. Schema Conflicts:

   • If schemas are manually modified in ZGW, the bundle’s auto-install may overwrite changes.
   • Fix: Disable auto-install in config/packages/common_gateway/vrijbrp_to_zgw.yaml:

     install_schemas: false
     

     Then manually merge schemas using commongateway:merge-schemas.

2. Authentication Issues:

   • ZGW API keys or OAuth tokens may expire silently.
   • Debug: Enable HTTP logging in config/packages/monolog.yaml:

     handlers:
         zgw_http:
             type: stream
             path: "%kernel.logs_dir%/zgw_http.log"
             level: debug
             channels: ["zgw"]
     

3. Rate Limiting:

   • ZGW may throttle requests during bulk syncs.
   • Mitigation: Configure batch sizes in config/packages/common_gateway/vrijbrp_to_zgw.yaml:

     sync:
         batch_size: 50  # Default: 100
     

4. Data Mismatches:

   • VrijBRP and ZGW may have incompatible data models (e.g., address vs. postal_address).
   • Tip: Use mapping services provided by the bundle:

     $mapper = $this->container->get('common_gateway.vrijbrp_to_zgw.mapper');
     $zgwData = $mapper->mapVrijBRPToZGW($vrijBRPData);
     

Debugging Tips

1. Dry Runs:

   • Test syncs without writing to ZGW:

     php artisan zgw:sync --dry-run
     

     (Symfony: php bin/console zgw:sync --dry-run)

2. Database Inspection:

   • Check sync status in the zgw_sync_jobs table:

     SELECT * FROM zgw_sync_jobs WHERE status = 'failed' ORDER BY created_at DESC;
     

3. Event Debugging:

   • Dump events in a listener:

     public function handleSyncEvent(SyncEvent $event)
     {
         \Log::debug('Sync Event Data:', [
             'entity' => $event->getEntity(),
             'action' => $event->getAction(),
         ]);
     }
     

Extension Points

1. Custom Sync Logic:

   • Override the default sync handler by extending the bundle’s service:

     # config/services.yaml
     CommonGateway\VrijBRPToZGWBundle\Sync\SyncHandler:
         class: App\Sync\CustomSyncHandler
         arguments:
             $defaultHandler: '@common_gateway.vrijbrp_to_zgw.sync.handler'
     

2. Webhook Integration:

   • Extend the bundle to support webhook-based syncs by implementing WebhookSyncInterface:

     use CommonGateway\VrijBRPToZGWBundle\Sync\WebhookSyncInterface;
     
     class CustomWebhookSync implements WebhookSyncInterface
     {
         public function handleWebhook(array $payload): void
         {
             // Custom logic for webhook payloads
         }
     }
     

3. UI Customization:

   • Add custom fields to the CommonGateway Admin UI by extending the plugin’s Twig templates:

     resources/views/common_gateway/vrijbrp_to_zgw/
     

   • Example: Override config.html.twig to add a sync status badge.