Haalcentraal To Stufbg Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation via Admin UI

   • Navigate to the Plugins tab in the Common Gateway admin interface.
   • Search for haalcentraal-to-stufbg-bundle and install it directly.

2. CLI Installation (Alternative)

   composer require common-gateway/haalcentraal-to-stufbg-bundle:dev-main
   php bin/console commongateway:install common-gateway/haalcentraal-to-stufbg-bundle
   

   (For Docker: Replace php with docker-compose exec php)

3. Verify Installation

   • Check the Plugins tab in the admin UI for the installed bundle.
   • Confirm schema registration via:

     php bin/console debug:container | grep stufbg
     

4. First Use Case: Data Transformation

   • Use the bundle to convert HaalCentraal (Dutch government data) to STUF-BG (Dutch e-government XML format).
   • Example workflow:

     use CommonGateway\HaalCentraalToStufBGBundle\Transformer\HaalCentraalToStufTransformer;
     
     $transformer = new HaalCentraalToStufTransformer();
     $stufXml = $transformer->transform($haalCentraalData);
     

Implementation Patterns

Core Workflows

1. Plugin-Based Data Mapping

   • Leverage the bundle’s transformer services to map HaalCentraal JSON/XML to STUF-BG XML.
   • Example: Extend HaalCentraalToStufTransformer for custom fields:

     class CustomHaalCentraalToStufTransformer extends HaalCentraalToStufTransformer {
         protected function mapCustomField($data) {
             return $this->createStufElement('CustomField', $data['custom_key']);
         }
     }
     

2. Schema Integration

   • Register custom STUF-BG schemas via config/packages/commongateway.yaml:

     commongateway:
         schemas:
             stufbg_custom:
                 path: '%kernel.project_dir%/config/schemas/stufbg'
                 format: xml
     

3. Event-Driven Processing

   • Hook into Common Gateway events (e.g., commongateway.plugin.installed) to trigger post-install logic:

     use Symfony\Component\EventDispatcher\GenericEvent;
     
     $dispatcher->addListener('commongateway.plugin.installed', function (GenericEvent $event) {
         if ($event->getSubject()->getName() === 'haalcentraal-to-stufbg-bundle') {
             // Post-install setup (e.g., cache warming)
         }
     });
     

4. API Integration

   • Use the bundle’s HTTP client to fetch HaalCentraal data and transform it:

     $client = $this->get('common_gateway.http_client');
     $haalCentraalData = $client->get('https://api.haalcentraal.nl/data')->toArray();
     $stufXml = $transformer->transform($haalCentraalData);
     

Best Practices

• Dependency Injection: Prefer injecting HaalCentraalToStufTransformer via Laravel’s container.
• Configuration: Centralize STUF-BG settings in config/services.php:

  'stufbg' => [
      'namespace' => 'urn:stuf:stufbg:1.0',
      'version' => '1.0',
  ],
  

• Testing: Mock HaalCentraalToStufTransformer in unit tests:

  $this->app->instance(
      HaalCentraalToStufTransformer::class,
      Mockery::mock(HaalCentraalToStufTransformer::class)
  );
  

Gotchas and Tips

Pitfalls

1. Schema Validation Failures

   • Issue: STUF-BG XML may fail validation if namespaces or required fields are missing.
   • Fix: Use php bin/console commongateway:validate-schema stufbg to debug.
   • Tip: Enable strict validation in config/packages/commongateway.yaml:

     commongateway:
         validation:
             strict: true
     

2. Plugin Discovery Issues

   • Issue: Bundle not appearing in the Plugins tab.
   • Fix:
     • Ensure composer.json includes "type": "symfony-bundle".
     • Clear cache:

       php bin/console cache:clear
       

     • Verify CommonGateway\HaalCentraalToStufBGBundle\HaalCentraalToStufBGBundle is autoloaded.

3. Namespace Conflicts

   • Issue: STUF-BG XML namespaces clash with other plugins.
   • Fix: Override namespaces in your transformer:

     $this->setNamespace('urn:custom:stufbg:1.0');
     

4. Performance with Large Datasets

   • Issue: Slow transformations for bulk data.
   • Fix: Use chunked processing:

     foreach ($largeDataset as $chunk) {
         $transformer->transform($chunk);
     }
     

Debugging Tips

• Log Transformer Output:

  $transformer->setDebug(true); // Logs raw XML to `var/log/transformer.log`
  

• Inspect HaalCentraal Data:

  php bin/console debug:container | grep haalcentraal
  

• Validate XML:

  xmllint --schema path/to/stufbg.xsd transformed.xml --noout
  

Extension Points

1. Custom Transformers

   • Extend BaseHaalCentraalToStufTransformer to add domain-specific logic:

     class MyDomainTransformer extends BaseHaalCentraalToStufTransformer {
         protected function mapDomainSpecificField($data) {
             // Custom logic
         }
     }
     

2. Hooks for Post-Transformation

   • Use Symfony events to act on transformed data:

     $dispatcher->addListener('commongateway.stufbg.transformed', function ($event) {
         $stufXml = $event->getData();
         // Store in DB, send to API, etc.
     });
     

3. Override Default Schemas

   • Replace bundled schemas by publishing assets:

     php bin/console assets:install public
     

   • Update config/packages/commongateway.yaml to point to your schemas.

4. Docker-Specific Quirks

   • Issue: Permissions errors when writing logs/schemas.
   • Fix: Ensure volumes are mounted correctly in docker-compose.yml:

     volumes:
         - ./var/log:/var/www/var/log