Sim Xml To Zgw Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Bundle

   composer require common-gateway/sim-xml-to-zgw-bundle:dev-main
   php bin/console commongateway:install common-gateway/sim-xml-to-zgw-bundle
   

   • Verify installation via the Common Gateway Admin UI under the Plugins tab.

2. Locate Core Configuration

   • Check config/packages/common_gateway_sim_xml_to_zgw.yaml (auto-generated) for default settings.
   • Review config/bundles.php to ensure the bundle is enabled.

3. First Translation Use Case

   • Use the bundle’s service to convert a SimXML message (e.g., from a SOAP request) into a ZGW-compatible object:

     use CommonGateway\SimXMLToZGWBundle\Service\SimXMLConverter;
     
     $converter = $this->container->get(SimXMLConverter::class);
     $zgwObject = $converter->convert($simXmlString);
     

   • Validate output against ZGW schema requirements (e.g., ZGW\Message\ZGWMessageInterface).

Implementation Patterns

Workflows

1. SOAP/SimXML Ingestion

   • Integrate with a Symfony HTTP kernel or FOSHttpCache to intercept incoming SimXML payloads (e.g., from a SOAP endpoint).
   • Example middleware:

     public function handle(Request $request, Closure $next): Response
     {
         if ($request->isXml()) {
             $simXml = $request->getContent();
             $zgwObject = $this->simXMLConverter->convert($simXml);
             // Proceed with ZGW logic...
         }
         return $next($request);
     }
     

2. Schema Validation

   • Use the bundle’s built-in validators to ensure SimXML conforms to ZGW standards:

     $validator = $this->container->get(SimXMLValidator::class);
     $errors = $validator->validate($simXml);
     if ($errors->count() > 0) {
         throw new \RuntimeException('Invalid SimXML: ' . $errors->get(0)->getMessage());
     }
     

3. Dynamic Plugin Extension

   • Extend functionality via custom converters or mappers:

     # config/packages/common_gateway_sim_xml_to_zgw.yaml
     common_gateway_sim_xml_to_zgw:
         custom_mappers:
             - App\Mapper\CustomSimXMLMapper
     

   • Implement CommonGateway\SimXMLToZGWBundle\Mapper\SimXMLMapperInterface for domain-specific logic.

4. Event-Driven Processing

   • Listen for simxml.converted events to react to translations:

     use CommonGateway\SimXMLToZGWBundle\Event\SimXMLConvertedEvent;
     
     $eventDispatcher->addListener(SimXMLConvertedEvent::class, function (SimXMLConvertedEvent $event) {
         // Post-process $event->getZGWObject()
     });
     

Integration Tips

• Leverage Symfony’s Dependency Injection: Autowire SimXMLConverter and related services in controllers/services.
• Logging: Use Monolog to track conversions:

  $this->logger->info('SimXML converted to ZGW', ['sim_xml' => $simXml, 'zgw_object' => $zgwObject]);
  

• Testing: Mock SimXMLConverter in PHPUnit:

  $this->mockBuilder->disableOriginalConstructor()
      ->getMockBuilder(SimXMLConverter::class)
      ->disableOriginalConstructor()
      ->onlyMethods(['convert'])
      ->getMock();
  

Gotchas and Tips

Pitfalls

1. Schema Mismatches

   • SimXML structures may not align with ZGW schemas. Use the bundle’s SchemaLoader to debug:

     $schema = $this->schemaLoader->load('zgw_schema.xsd');
     $validator->validateAgainstSchema($simXml, $schema);
     

   • Fix: Extend SimXMLConverter to handle custom mappings or pre-process XML.

2. Circular Dependencies

   • Avoid injecting SimXMLConverter into services that are also autowired as bundle dependencies (e.g., mappers). Use constructor injection sparingly.

3. Admin UI Discovery Issues

   • If the plugin doesn’t appear in the Common Gateway Admin UI:
     • Verify composer.json includes "type": "symfony-bundle".
     • Clear cache: php bin/console cache:clear.

4. Namespace Collisions

   • The bundle assumes ZGW\ namespace for output objects. Override with:

     common_gateway_sim_xml_to_zgw:
         zgw_namespace: App\ZGW\
     

Debugging

• Enable Verbose Logging

  php bin/console debug:config common_gateway_sim_xml_to_zgw
  

  Set debug: true in config to log raw SimXML/ZGW payloads.

• Dump Converter State

  $converter->setDebug(true); // Temporarily enable debug mode
  

Extension Points

1. Custom Mappers

   • Override default field mappings by implementing SimXMLMapperInterface:

     class CustomFieldMapper implements SimXMLMapperInterface {
         public function map(array $simXmlData): array {
             return [
                 'custom_field' => $simXmlData['legacy_field'] ?? null,
             ];
         }
     }
     

   • Register in config:

     common_gateway_sim_xml_to_zgw:
         custom_mappers:
             - App\CustomFieldMapper
     

2. Post-Conversion Hooks

   • Use the simxml.post_convert event to modify ZGW objects:

     $eventDispatcher->addListener(SimXMLPostConvertEvent::class, function (SimXMLPostConvertEvent $event) {
         $event->setZGWObject($this->enrichZGWObject($event->getZGWObject()));
     });
     

3. Schema Customization

   • Extend default schemas by overriding the schema_path config:

     common_gateway_sim_xml_to_zgw:
         schema_path: '%kernel.project_dir%/config/zgw_schemas'
     

Performance Tips

• Cache Schema Loads

  common_gateway_sim_xml_to_zgw:
      schema_cache_enabled: true
  

• Batch Processing For large payloads, use SimXMLBatchConverter:

  $batchConverter = $this->container->get(SimXMLBatchConverter::class);
  $results = $batchConverter->convertBatch([$simXml1, $simXml2]);