Zgw To Open Belasting Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The bundle is tailored for ZGW (Zaken API Gateway) to Open Belastingen (PINK API) data transformation, specifically converting ZGW cases into tax assessments (aanslagen) and objections (bezwaren). This aligns well with government/tax domain systems built on Symfony/Laravel, particularly where interoperability with Dutch public sector APIs is required.
• Modularity: As a Symfony Flex bundle, it follows a plugin-based architecture, enabling loose coupling with the host application. This is ideal for microservices or modular monoliths where domain-specific logic (e.g., tax processing) can be isolated.
• Schema & Mapping Logic: The bundle encapsulates XML/JSON schema definitions and business logic for transformations, reducing boilerplate in the host application. This is valuable for highly regulated domains where compliance with API contracts (e.g., ZGW, PINK) is critical.
• Laravel Compatibility: While Symfony-native, the bundle can be integrated into Laravel via Symfony Bridge or Lumen, though this introduces abstraction overhead. Native Laravel packages (e.g., spatie/laravel-symfony-bundle) may be needed.

Integration Feasibility

• Symfony Ecosystem: If the host application is Symfony, integration is straightforward (Flex recipes, autoloading, dependency injection). For Laravel, additional glue code (e.g., service wrappers, event listeners) will be required to bridge Symfony components (e.g., HttpClient, Serializer).
• API Contracts: The bundle assumes ZGW-compliant input and PINK API-compliant output. The host system must:
  • Validate incoming ZGW payloads (e.g., using zorgdracht/zgw-common).
  • Handle PINK API authentication (OAuth2, API keys) separately.
• Database Agnosticism: The bundle appears stateless (no ORM dependencies), but the host may need to persist transformed data (e.g., aanslagen) in its own database.

Technical Risk

Key Questions

1. Host System Requirements:
   • Is the host application Symfony or Laravel? If Laravel, what’s the migration path for Symfony bundles?
   • Does the host already use ZGW/PINK APIs, or is this a greenfield integration?
2. Data Flow:
   • How are ZGW cases ingested? (e.g., webhook, batch file, direct API call)
   • Where will transformed aanslagen/bezwaren be stored? (Host DB, PINK API, or both?)
3. Compliance:
   • Are there additional validation rules beyond ZGW/PINK schemas (e.g., business logic for tax calculations)?
   • How will audit logs be handled for transformations?
4. Extensibility:
   • Will custom mappings be needed beyond the bundle’s defaults?
   • Is there a need to extend the bundle (e.g., add new PINK API endpoints)?
5. Operations:
   • What’s the expected throughput (e.g., cases/sec)? Will the bundle need scaling (e.g., queue-based processing)?
   • Are there SLA requirements for transformation latency?

Integration Approach

Stack Fit

Migration Path (Laravel)

1. Add Symfony Bridge:

   composer require spatie/laravel-symfony-bundle
   

   Configure config/symfony.php to include the bundle’s paths.

2. Bundle Registration:

   • Register the bundle in config/app.php (Symfony) or via spatie bridge (Laravel).
   • For Laravel, create a service provider to expose bundle services:

     public function register() {
         $this->app->singleton('zgw_to_open_belasting.transformer', function ($app) {
             return include __DIR__.'/../../vendor/common-gateway/zgw-to-open-belasting-bundle/Resources/config/services.php';
         });
     }
     

3. Dependency Mapping:

   • Replace Symfony-specific dependencies (e.g., HttpClient) with Laravel equivalents or wrap them:

     // Example: Wrap Symfony HttpClient in Laravel HTTP client
     $symfonyClient = new \Symfony\Contracts\HttpClient\HttpClient();
     $laravelClient = new \Illuminate\Http\Client\PendingRequest($symfonyClient->getBaseUri());
     

4. Event Translation:

   • Subscribe to bundle events (Symfony) and dispatch Laravel events:

     use Symfony\Component\EventDispatcher\EventDispatcherInterface;
     
     $dispatcher = new EventDispatcher();
     $dispatcher->addListener('zgw.zaken.transformed', function ($event) {
         event(new \App\Events\ZgwTransformed($event->getData()));
     });
     

5. Testing:

   • Write Laravel-specific tests for:
     • Queue jobs (if using async processing).
     • Cached responses (if applicable).
     • Laravel middleware interactions.

Compatibility

• Symfony: High compatibility (designed for Symfony 5.4+).
• Laravel:
  • Medium compatibility (requires abstraction layers).
  • Limitations:
    • No native support for Symfony bundles.
    • Potential conflicts with Laravel’s service container.
    • Event system differences may need manual bridging.
• PHP Version: Requires PHP 8.0+ (check Laravel version compatibility).

Sequencing

1. Pre-Integration:

   • Audit the host system’s current ZGW/PINK integration (if any).
   • Set up a development environment with both Symfony and Laravel stacks to test bridging.

2. Core Integration:

   • Install and configure the bundle.
   • Implement service wrappers for Symfony-specific components.
   • Test basic transformations (ZGW → PINK payloads).

3. Extensibility:

   • Add custom mappings or business logic if needed.
   • Integrate with host workflows (e.g., queues, notifications).

4. Production Readiness:

   • Implement monitoring for transformation failures.
   • Set up rollback procedures (e.g., database migrations for schema changes).
   • Document Laravel-specific quirks (e.g., event translation).

Operational Impact

Maintenance

• Bundle Updates:
  • Monitor common-gateway/zgw-to-open-belasting-bundle for updates.
  • Risk: Breaking changes in ZGW/PINK APIs may require bundle forks or patches.
  • Mitigation: Use semantic versioning and test updates in staging.
• Dependency Management:
  • Symfony bundles may pull in unnecessary dependencies (e.g., symfony/validator).
  • Solution: Use composer exclude or custom installers to trim dependencies.
• Custom Logic:
  • Extensions to the bundle (e.g., new P