Huwelijksplanner Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require common-gateway/huwelijksplanner-bundle

Add the bundle to config/bundles.php:

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

2. Configuration Load the default config via config/packages/huwelijksplanner.yaml (auto-generated). Override as needed:

   huwelijksplanner:
       plugins:
           - CommonGateway\Huwelijksplanner\Plugin\MarriageRegistrationPlugin
           - CommonGateway\Huwelijksplanner\Plugin\WeddingLocationPlugin
       api:
           base_uri: '%env(HUWELIJKSPLANNER_API_URL)%'
   

3. First Use Case: Marriage Request Flow Trigger the marriage registration workflow via a controller:

   use CommonGateway\HuwelijksplannerBundle\Service\MarriageWorkflow;
   
   public function startMarriageRequest(MarriageWorkflow $workflow)
   {
       $request = $workflow->createRequest([
           'partner1' => ['bsn' => '123456789', 'name' => 'Doe, John'],
           'partner2' => ['bsn' => '987654321', 'name' => 'Smith, Jane'],
       ]);
       return $this->redirectToRoute('huwelijksplanner.marriage_steps', ['id' => $request->getId()]);
   }
   

Implementation Patterns

Core Workflows

1. Plugin-Based Architecture

   • Registration: Enable/disable plugins via config:

     huwelijksplanner:
         plugins:
             - { name: MarriageRegistrationPlugin, enabled: true }
             - { name: WeddingLocationPlugin, enabled: false }
     

   • Extension: Create custom plugins by implementing PluginInterface:

     class CustomValidationPlugin implements PluginInterface
     {
         public function validate(MarriageRequest $request): bool
         {
             // Custom logic
         }
     }
     

2. API Integration

   • Proxy Pattern: Use the HuwelijksplannerApiClient to interact with municipal APIs:

     $client = $this->container->get('huwelijksplanner.api_client');
     $response = $client->get('/marriage-status', ['bsn' => '123456789']);
     

   • Event-Driven: Subscribe to API events (e.g., MarriageApprovedEvent) in your services:

     public function __construct(HuwelijksplannerEvents $events)
     {
         $events->on('marriage.approved', [$this, 'notifyCouple']);
     }
     

3. Form Handling

   • Step-Based Forms: Leverage the MarriageStepHandler for multi-step forms:

     $handler = new MarriageStepHandler($request);
     $form = $handler->getCurrentStepForm(); // Returns FormInterface
     

   • Validation: Use built-in validators (e.g., BSNValidator, AgeValidator) or extend:

     $validator = new CustomValidator();
     $errors = $validator->validate($request);
     

4. Data Persistence

   • Doctrine Entities: Extend MarriageRequest or WeddingLocation entities:

     #[ORM\Entity]
     class CustomMarriageRequest extends MarriageRequest
     {
         #[ORM\Column]
         private string $customField;
     }
     

   • Repositories: Inject MarriageRequestRepository for CRUD operations:

     $request = $repository->find($id);
     $repository->save($request);
     

Gotchas and Tips

Common Pitfalls

1. Plugin Loading Order

   • Issue: Plugins may depend on each other (e.g., WeddingLocationPlugin needs MarriageRegistrationPlugin).
   • Fix: Define a priority in config:

     plugins:
         - { name: MarriageRegistrationPlugin, priority: 10 }
         - { name: WeddingLocationPlugin, priority: 20 }
     

2. BSN Validation

   • Issue: The BSNValidator is strict (Dutch BSN format only). Custom formats may fail.
   • Fix: Extend the validator or bypass it for testing:

     $validator = new BSNValidator();
     $validator->setStrict(false); // Temporarily disable strict checks
     

3. API Rate Limiting

   • Issue: Municipal APIs often throttle requests. Unhandled exceptions can break workflows.
   • Fix: Implement retry logic with HuwelijksplannerApiClient:

     $client = new HuwelijksplannerApiClient($httpClient, [
         'max_retries' => 3,
         'delay' => 1000,
     ]);
     

4. Entity Inheritance

   • Issue: Overriding MarriageRequest may cause hydration issues if properties aren’t mapped.
   • Fix: Use @ORM\Attribute annotations explicitly:

     #[ORM\Column(name: 'custom_field', type: 'string')]
     private string $customField;
     

Debugging Tips

1. Event Listener Debugging

   • Enable event logging in config/packages/dev/huwelijksplanner.yaml:

     huwelijksplanner:
         debug:
             events: true
     

   • Check logs for dispatched events (e.g., MarriageRequestCreatedEvent).

2. API Debugging

   • Enable HTTP client logging:

     $client = new HuwelijksplannerApiClient($httpClient, [
         'logger' => $this->container->get('monolog.logger.huwelijksplanner'),
     ]);
     

3. Form Debugging

   • Dump form errors in templates:

     {% for error in form.errors %}
         {{ error.message }}
     {% endfor %}
     

Extension Points

1. Custom Validators

   • Create a validator service and tag it:

     services:
         App\Validator\CustomMarriageValidator:
             tags: [huwelijksplanner.validator]
     

2. API Response Transformers

   • Override the ApiResponseTransformer to modify responses:

     $transformer = new CustomApiResponseTransformer();
     $client->setTransformer($transformer);
     

3. Workflow Steps

   • Add custom steps by implementing StepInterface:

     class CustomStep implements StepInterface
     {
         public function getName(): string { return 'custom_step'; }
         public function render(TemplateRenderer $renderer): string { /* ... */ }
     }
     

   • Register the step in config:

     huwelijksplanner:
         workflow:
             steps:
                 - App\Step\CustomStep
     

4. Municipality-Specific Logic

   • Use the MunicipalityContext service to inject location-specific rules:

     $context = $this->container->get('huwelijksplanner.municipality_context');
     if ($context->isAmsterdam()) {
         // Custom Amsterdam rules
     }
     

```markdown
### Configuration Quirks
1. **Environment Variables**
   - The bundle expects `HUWELIJKSPLANNER_API_URL` and `HUWELIJKSPLANNER_MUNICIPALITY_CODE` in `.env`. If missing, the bundle throws a `RuntimeException`.
   - **Fix**: Set defaults in `config/packages/huwelijksplanner.yaml`:
     ```yaml
     api:
         base_uri: '%env(default::HUWELIJKSPLANNER_API_URL)%'
     ```

2. **Doctrine Migrations**
   - Running migrations after extending entities may fail if the bundle’s schema isn’t updated first.
   - **Fix**: Run the bundle’s migrations first:
     ```bash
     php bin/console doctrine:migrations:execute --up --query="SELECT * FROM migration_version WHERE version = 'CommonGatewayHuwelijksplannerBundle'"
     ```

3. **Caching**
   - The bundle caches API responses by default. Clear cache after plugin changes:
     ```bash
     php bin/console cache:clear huwelijksplanner
     ```

### Performance Tips
1. **Batch Processing**
   - Use `MarriageRequestBatchProcessor` for bulk operations:
     ```php
     $processor = new MarriageRequestBatchProcessor($repository);
     $processor->process($requests, 50); // Batch size of 50
     ```

2. **Lazy Loading**
   - Enable lazy loading for large datasets:
     ```php
     $requests = $repository->findBy([], [], 100, 0, ['partner1' => 'ASC']);
     ```

3. **API Caching**
   - Cache frequent