Huwelijk Vrijbrp Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require common-gateway/huwelijk-vrijbrp-bundle
   

   Ensure your project uses Common Gateway CoreBundle (required dependency).

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

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

3. Database Migrations Run migrations to create required tables:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

4. First Use Case: Register a Marriage Use the provided API or CLI command to create a marriage record:

   php bin/console app:huwelijk:create --partner1=123 --partner2=456 --date=2024-01-01
   

   Verify in the database (huwelijk table) or via the admin interface (if configured).

Where to Look First

• Documentation: Conductor Gateway Plugins (core plugin system).
• Bundle Configuration: config/packages/huwelijk_vrijbrp.yaml (if auto-generated).
• Entities: src/Entity/Huwelijk.php (core model).
• Commands: src/Command/ (CLI tools for testing).
• Services: src/Service/ (business logic, e.g., HuwelijkService).

Implementation Patterns

Workflows

1. Marriage Registration

   • API Route: Extend HuwelijkController or create a custom endpoint:

     // src/Controller/CustomHuwelijkController.php
     use CommonGateway\HuwelijkVrijBRPBundle\Controller\HuwelijkController;
     
     class CustomHuwelijkController extends HuwelijkController {
         public function customAction(Request $request) {
             $this->huwelijkService->registerMarriage($request->request->all());
             return new JsonResponse(['status' => 'success']);
         }
     }
     

   • Form Integration: Use HuwelijkType (Symfony form) in your templates:

     {{ form_start(form) }}
         {{ form_row(form.partner1) }}
         {{ form_row(form.partner2) }}
         {{ form_row(form.date) }}
     {{ form_end(form) }}
     

2. Data Synchronization with VrijBRP

   • Use HuwelijkSyncService to push/pull data to/from VrijBRP:

     $syncService = $this->container->get('huwelijk_vrijbrp.sync_service');
     $syncService->syncMarriage($huwelijkEntity);
     

3. Event Listeners

   • Subscribe to HuwelijkEvents (e.g., HuwelijkCreatedEvent) for post-registration logic:

     // src/EventListener/HuwelijkListener.php
     use CommonGateway\HuwelijkVrijBRPBundle\Event\HuwelijkEvents;
     
     class HuwelijkListener {
         public function onHuwelijkCreated(HuwelijkCreatedEvent $event) {
             // Send notification, log, etc.
         }
     }
     

     Register in services.yaml:

     services:
         App\EventListener\HuwelijkListener:
             tags:
                 - { name: kernel.event_listener, event: huwelijk.created, method: onHuwelijkCreated }
     

Integration Tips

• Custom Fields: Extend Huwelijk entity to add fields (e.g., witnesses, location):

  // src/Entity/Huwelijk.php
  /**
   * @ORM\Column(type="string", nullable=true)
   */
  private $location;
  

  Update migrations and forms accordingly.

• Validation: Override validation rules in HuwelijkType:

  // src/Form/HuwelijkType.php
  $builder->add('date', DateType::class, [
      'constraints' => [
          new NotBlank(),
          new Callback([$this, 'validateDate']),
      ],
  ]);
  

• API Integration: Use Symfony’s Serializer to expose marriage data:

  // src/Serializer/HuwelijkNormalizer.php
  use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
  
  class HuwelijkNormalizer implements NormalizerInterface {
      public function normalize($object, $format = null, array $context = []) {
          return [
              'id' => $object->getId(),
              'partners' => [$object->getPartner1(), $object->getPartner2()],
              'date' => $object->getDate()->format('Y-m-d'),
          ];
      }
  }
  

• Testing: Use HuwelijkTestCase (if provided) or mock the HuwelijkService:

  $this->container->get('huwelijk_service')->method('registerMarriage')
      ->willReturn($huwelijkEntity);
  

Gotchas and Tips

Pitfalls

1. Missing Dependencies

   • Ensure common-gateway/core-bundle and vrijbrp/vrijbrp are installed. The bundle assumes these are present.
   • Fix: Run composer require common-gateway/core-bundle vrijbrp/vrijbrp.

2. Database Schema Mismatches

   • The bundle’s migrations may conflict with existing huwelijk tables.
   • Fix: Review src/Resources/migrations/ and adjust or drop tables before re-running migrations.

3. VrijBRP API Credentials

   • The bundle requires VrijBRP API access (e.g., for syncing). Missing credentials will cause silent failures.
   • Fix: Configure huwelijk_vrijbrp.yaml:

     huwelijk_vrijbrp:
         vrijbrp:
             api_url: "https://vrijbrp.example.com/api"
             client_id: "%env(VRIJBRP_CLIENT_ID)%"
             client_secret: "%env(VRIJBRP_CLIENT_SECRET)%"
     

4. Event Dispatching

   • Events like huwelijk.created may not fire if the bundle isn’t fully initialized.
   • Fix: Ensure the bundle is loaded after CoreBundle in bundles.php.

5. Partner Validation

   • The bundle assumes partners exist in the BRP system. Invalid IDs (e.g., non-existent BSNs) may not throw clear errors.
   • Fix: Add custom validation in HuwelijkType:

     $builder->add('partner1', EntityType::class, [
         'class' => 'App\Entity\Persoon',
         'constraints' => [new ValidBSN()],
     ]);
     

Debugging Tips

1. Enable Debug Mode Add to .env:

   APP_DEBUG=1
   HUWELIJK_VRIJBRP_DEBUG=1
   

   This logs sync operations and API calls.

2. Log Sync Errors Override HuwelijkSyncService to log failures:

   public function syncMarriage(Huwelijk $huwelijk) {
       try {
           // Sync logic...
       } catch (\Exception $e) {
           $this->logger->error('Sync failed for huwelijk ID ' . $huwelijk->getId(), ['error' => $e->getMessage()]);
           throw $e;
       }
   }
   

3. Check API Responses Use HUWELIJK_VRIJBRP_API_DEBUG=1 to log raw VrijBRP API responses.

Extension Points

1. Custom Marriage Types Extend Huwelijk entity to support different marriage types (e.g., civil, religious):

   // src/Entity/Huwelijk.php
   public const TYPE_CIVIL = 'civil';
   public const TYPE_RELIGIOUS = 'religious';
   
   /**
    * @ORM\Column(type="string")
    */
   private $type;
   

2. Webhooks Add a HuwelijkWebhookService to notify external systems:

   // src/Service/HuwelijkWebhookService.php
   public function sendCreatedWebhook(Huwelijk $huwelijk) {
       $client = new \GuzzleHttp\Client();
       $client->post('https://external-system.com/webhook', [
           'json' => ['huwelijk' => $huwelijk->getId()],
       ]);
   }
   

3. Batch Processing Use Symfony’s Messenger component to process marriages asynchronously:

   // src/Message/HuwelijkSyncMessage.php
   class HuwelijkSyncMessage {
       public function __construct(private Huwelijk $huwelijk) {}
   }
   
   // src/MessageHandler/HuwelijkSyncHandler.php
   class HuwelijkSyncHandler {
       public function __invoke(HuwelijkSyncMessage $message