Zds To Zgw Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Understand the Ecosystem Context

   • This bundle is designed for Common Gateway, a Dutch government API ecosystem for ZorgDomein (healthcare) integrations.
   • Target use case: Extending ZDS (ZorgDomein Services) functionality to ZGW (Zorgportal Gateway) via Symfony Flex bundles.

2. Prerequisites

   • Install Common Gateway Core (base project) via their docs.
   • Ensure your project uses Symfony Flex (auto-discovery of bundles).

3. First Use Case: Creating a Basic Plugin

   • Clone this repo as a template: composer create-project common-gateway/zds-to-zgw-bundle my-plugin-bundle.
   • Replace PetStoreBundle references with your bundle name (e.g., MyHealthcareBundle).
   • Implement a ZGW-compatible API endpoint (e.g., /api/v1/patients) in src/Controller/ using the provided ZGWBaseController.

4. Installation

   • Add to your project:

     composer require common-gateway/my-healthcare-bundle:dev-main
     php bin/console commongateway:install common-gateway/my-healthcare-bundle
     

   • Verify in Common Gateway Admin UI under Plugins.

Implementation Patterns

Core Workflows

1. Bundle Structure

   • Follow the template’s layout:

     src/
       Controller/ZGWBaseController.php  # Extend this for API routes
       Entity/                           # Define ZDS/ZGW entities (e.g., Patient, Appointment)
       Service/                          # Business logic (e.g., PatientService)
       Resources/config/                 # YAML/XML schemas for ZGW
     

   • Key Files:
     • src/DependencyInjection/: Override services via my_plugin.extension.php.
     • config/packages/: Add Symfony config (e.g., routing, validation).

2. ZGW Integration

   • Schemas: Define ZGW-compatible XML/JSON schemas in Resources/config/. Example: Map a Patient entity to ZGW’s Zorgaanbieder schema.
   • Controllers: Extend ZGWBaseController to handle:
     • Request validation (use ZGWValidator).
     • Response formatting (use ZGWResponseFactory).
     • Example route:

       # config/routes.yaml
       my_healthcare.api:
         resource: "@MyHealthcareBundle/Resources/config/routing.yaml"
         type: annotation
       

3. ZDS ↔ ZGW Translation

   • Use Doctrine ORM to map ZDS entities to ZGW schemas.
   • Example service method:

     // src/Service/PatientService.php
     public function toZGWPatient(ZdsPatient $patient): array {
         return [
             'zorgaanbieder' => [
                 'naam' => $patient->getName(),
                 'bsn' => $patient->getBsn(),
             ],
         ];
     }
     

4. Admin UI Plugin Management

   • The bundle auto-registers in Common Gateway’s Plugins tab.
   • Customize plugin metadata in src/Resources/config/plugin.yaml:

     name: "My Healthcare Plugin"
     description: "Extends ZGW with patient management."
     version: "1.0.0"
     

Integration Tips

• Dependency Injection: Use Symfony’s autowiring for services (e.g., PatientService).
• Testing: Mock ZGWBaseController and test schema validation with PHPUnit.
• Logging: Inject Psr\Log\LoggerInterface to log ZGW requests/responses.
• Caching: Cache ZGW schemas if performance is critical (use Symfony\Component\Cache).

Gotchas and Tips

Pitfalls

1. Schema Validation Failures

   • Issue: ZGW rejects malformed XML/JSON.
   • Fix: Use ZGWValidator in controllers:

     $validator = $this->get('zgw_validator');
     $errors = $validator->validate($requestData);
     if ($errors->count()) { throw new \RuntimeException($errors->get(0)->getMessage()); }
     

   • Tip: Validate schemas locally with XMLSchema or JSON Schema Validator.

2. Bundle Auto-Discovery

   • Issue: Bundle isn’t detected by Common Gateway.
   • Fix:
     • Ensure composer.json has "type": "symfony-bundle".
     • Run composer dump-autoload after adding the bundle.
     • Verify config/bundles.php includes your bundle.

3. ZGW-Specific Quirks

   • BSN Validation: Dutch BSN (social security number) must be validated per Dutch regulations. Use common-gateway/validation bundle:

     $this->get('validator')->validate($patient->getBsn(), new BSN());
     

   • Security Headers: ZGW requires X-ZGW-API-Version header. Add middleware:

     // src/EventListener/ZGWHeaderListener.php
     public function onKernelRequest(GetResponseEvent $event) {
         $request = $event->getRequest();
         $request->headers->set('X-ZGW-API-Version', '2.0.0');
     }
     

4. Database Migrations

   • Issue: ZDS/ZGW entity changes break migrations.
   • Fix:
     • Use Doctrine migrations (make:migration).
     • For ZGW schemas, version them in Resources/config/schemas/v1/, v2/, etc.

Debugging Tips

• Enable ZGW Debug Mode:

  # config/packages/zgw.yaml
  zgw:
      debug: true  # Logs all ZGW requests/responses
  

• Check Common Gateway Logs:

  tail -f var/log/dev.log | grep "ZGW"
  

• Test Locally with ZGW Mock: Use ZGW Mock Server to simulate ZGW responses.

Extension Points

1. Custom ZGW Profiles

   • Extend ZGWBaseController to support multiple ZGW profiles (e.g., Zorgaanbieder, Zorgleverancier):

     class MyCustomController extends ZGWBaseController {
         protected $profile = 'zorgaanbieder';
     }
     

2. Webhook Integration

   • Add a WebhookController to handle ZGW webhook callbacks (e.g., for Zorgaanvraag updates):

     #[Route('/webhook/zorgaanvraag', name: 'zgw_webhook', methods: ['POST'])]
     public function handleWebhook(Request $request): Response {
         $payload = json_decode($request->getContent(), true);
         // Process webhook...
     }
     

3. GraphQL Layer

   • Use api-platform to expose ZDS data via GraphQL for frontend consumers:

     composer require api
     

     Configure in config/packages/api_platform.yaml.

4. Async Processing

   • Offload heavy ZGW operations to a queue (e.g., symfony/messenger):

     $this->get('messenger')->dispatch(new ProcessZGWRequest($data));