Geboorte Vrijbrp Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer in a Symfony project using Common Gateway:

   composer require common-gateway/geboorte-vrijbrp-bundle
   

   Enable the bundle in config/bundles.php:

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

2. Configuration Configure the bundle in config/packages/geboorte_vrijbrp.yaml:

   geboorte_vrijbrp:
       api_endpoint: '%env(GEBOORTE_API_ENDPOINT)%'
       api_key: '%env(GEBOORTE_API_KEY)%'
       timeout: 30
   

   Ensure environment variables are set in .env.

3. First Use Case Inject the GeboorteClient service and call the registerBirth method:

   use CommonGateway\GeboorteVrijBRPBundle\Service\GeboorteClient;
   
   class BirthController
   {
       public function __construct(private GeboorteClient $geboorteClient) {}
   
       public function registerBirth(Request $request)
       {
           $data = $request->request->all();
           $response = $this->geboorteClient->registerBirth($data);
           return new JsonResponse($response);
       }
   }
   

Implementation Patterns

Core Workflows

1. Birth Registration Use GeboorteClient::registerBirth() to submit birth data to VrijBRP:

   $birthData = [
       'mother_id' => '12345',
       'child_data' => [
           'first_name' => 'John',
           'last_name' => 'Doe',
           'birth_date' => '2023-10-15',
       ],
   ];
   $response = $this->geboorteClient->registerBirth($birthData);
   

2. Data Validation Validate input data using Symfony’s Validator before passing it to the client:

   use Symfony\Component\Validator\Validator\ValidatorInterface;
   
   public function registerBirth(Request $request, ValidatorInterface $validator)
   {
       $data = $request->request->all();
       $errors = $validator->validate($data, BirthDataConstraints::class);
   
       if (count($errors) > 0) {
           return new JsonResponse(['errors' => (string) $errors], 400);
       }
   
       return $this->geboorteClient->registerBirth($data);
   }
   

3. Event Listeners Attach listeners to GeboorteEvents (e.g., BirthRegisteredEvent) for post-processing:

   use CommonGateway\GeboorteVrijBRPBundle\Event\BirthRegisteredEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class BirthNotificationSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               BirthRegisteredEvent::class => 'onBirthRegistered',
           ];
       }
   
       public function onBirthRegistered(BirthRegisteredEvent $event)
       {
           // Send notification, log, or trigger other actions
       }
   }
   

Integration Tips

• Common Gateway Integration Extend the GeboortePlugin class to customize behavior:

  use CommonGateway\GeboorteVrijBRPBundle\Plugin\GeboortePlugin;
  
  class CustomGeboortePlugin extends GeboortePlugin
  {
      public function registerBirth(array $data): array
      {
          // Custom logic before/after API call
          return parent::registerBirth($data);
      }
  }
  

  Register the custom plugin in config/packages/geboorte_vrijbrp.yaml:

  geboorte_vrijbrp:
      plugin_class: App\Plugin\CustomGeboortePlugin
  

• API Rate Limiting Implement a decorator for the GeboorteClient to handle rate limits:

  use CommonGateway\GeboorteVrijBRPBundle\Service\GeboorteClientInterface;
  
  class RateLimitedGeboorteClient implements GeboorteClientInterface
  {
      public function __construct(private GeboorteClientInterface $decorated) {}
  
      public function registerBirth(array $data): array
      {
          // Check rate limits before calling $this->decorated->registerBirth($data)
          return $this->decorated->registerBirth($data);
      }
  }
  

Gotchas and Tips

Pitfalls

1. API Key Management

   • Hardcoding API keys in config is insecure. Use Symfony’s %env() and .env files.
   • Rotate keys periodically and implement key revocation logic in the GeboorteClient.

2. Data Validation Mismatches

   • The VrijBRP API may reject malformed data silently. Always validate input against the VrijBRP API spec before submission.
   • Example validation constraint:

     use Symfony\Component\Validator\Constraints as Assert;
     
     class BirthDataConstraints
     {
         public function __construct()
         {
             $this->birthDate = new Assert\DateTime([
                 'message' => 'Birth date must be in the past.',
                 'format' => 'Y-m-d',
             ]);
         }
     }
     

3. Timeout Handling

   • The default timeout (30s) may be insufficient for high-latency APIs. Adjust in config:

     geboorte_vrijbrp:
         timeout: 60  # Increase as needed
     

4. Plugin Isolation

   • Overriding the default GeboortePlugin may break updates. Prefer composition over inheritance for critical logic.

Debugging

• Enable API Logging Configure Monolog to log API requests/responses:

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

  Add a subscriber to log events:

  use Monolog\Logger;
  
  class GeboorteLoggerSubscriber implements EventSubscriberInterface
  {
      public function __construct(private Logger $logger) {}
  
      public static function getSubscribedEvents()
      {
          return [
              BirthRegisteredEvent::class => 'logBirthRegistration',
          ];
      }
  
      public function logBirthRegistration(BirthRegisteredEvent $event)
      {
          $this->logger->info('Birth registered', ['data' => $event->getData()]);
      }
  }
  

• Mocking the Client for Tests Use PHPUnit’s createMock to isolate tests:

  use CommonGateway\GeboorteVrijBRPBundle\Service\GeboorteClientInterface;
  
  public function testBirthRegistration()
  {
      $mockClient = $this->createMock(GeboorteClientInterface::class);
      $mockClient->method('registerBirth')->willReturn(['success' => true]);
  
      $controller = new BirthController($mockClient);
      $response = $controller->registerBirth(new Request([], [], ['data' => []]));
  
      $this->assertEquals(['success' => true], json_decode($response->getContent(), true));
  }
  

Extension Points

1. Custom API Endpoints Extend the GeboorteClient to support additional VrijBRP endpoints:

   class ExtendedGeboorteClient extends GeboorteClient
   {
       public function fetchBirthCertificate(string $birthId): array
       {
           return $this->callApi('GET', "/births/{$birthId}/certificate");
       }
   }
   

2. Webhook Support Implement a WebhookListener to handle VrijBRP webhook callbacks:

   use Symfony\Component\HttpKernel\Event\RequestEvent;
   
   class VrijBRPWebhookListener
   {
       public function onKernelRequest(RequestEvent $event)
       {
           if ($event->getRequest()->getPathInfo() === '/vrijbrp/webhook') {
               $data = json_decode($event->getRequest()->getContent(), true);
               // Process webhook data (e.g., validate signature, update local records)
           }
       }
   }
   

3. Database Sync Use Doctrine events to sync birth records with your database:

   use Doctrine\ORM\Event\LifecycleEventArgs;
   
   class BirthSyncSubscriber implements EventSubscriberInterface
   {
       public function postPersist(Birth $birth, LifecycleEventArgs $args)
       {
           $this->geboorteClient->registerBirth($birth->toArray());
       }
   }