Sim Tax To Zgw Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle to your Laravel project via Composer:

   composer require common-gateway/sim-tax-to-zgw-bundle
   

   Register the bundle in config/bundles.php:

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

2. Configuration Publish the default configuration:

   php artisan vendor:publish --tag=sim-tax-to-zgw-config
   

   Update config/sim_tax_to_zgw.php with your API endpoints, credentials, and schema paths.

3. First Use Case Convert a SimTax XML file to a ZGW-compliant JSON payload:

   use CommonGateway\SimTaxToZGWBundle\Service\TaxConverter;
   
   $converter = app(TaxConverter::class);
   $simTaxXml = file_get_contents('path/to/sim_tax.xml');
   $zgwPayload = $converter->convertToZGW($simTaxXml);
   

Where to Look First

• Bundle Documentation: Check the README for schema mappings and API specifications.
• Service Layer: Focus on TaxConverter for core conversion logic.
• Config File: Review config/sim_tax_to_zgw.php for API endpoints and validation rules.
• Tests: Study tests/ for usage examples and edge cases.

Implementation Patterns

Core Workflows

1. XML-to-ZGW Conversion Use TaxConverter to transform SimTax XML into ZGW-compliant JSON:

   $converter = app(TaxConverter::class);
   $result = $converter->convertToZGW($xmlContent, [
       'schema_version' => '2.0',
       'target_api' => 'pink-open-belastingen',
   ]);
   

2. ZGW-to-XML Conversion Reverse the process for responses or debugging:

   $zgwJson = '{"api_version": "2.0", ...}';
   $simTaxXml = $converter->convertFromZGW($zgwJson);
   

3. Validation Validate XML/JSON against schemas before conversion:

   $validator = app(\CommonGateway\SimTaxToZGWBundle\Validator\TaxValidator::class);
   $errors = $validator->validate($xmlContent);
   

Integration Tips

• API Layer Integrate with Laravel HTTP clients (e.g., Guzzle) for API calls:

  $client = app(\Illuminate\Support\Facades\Http::class);
  $response = $client->post('https://api.zgw.nl/pink-open-belastingen', [
      'headers' => ['Authorization' => 'Bearer ' . config('sim_tax_to_zgw.api_token')],
      'body' => $zgwPayload,
  ]);
  

• Event Handling Dispatch events for pre/post-conversion logic:

  event(new \CommonGateway\SimTaxToZGWBundle\Events\TaxConversionStarted($xmlContent));
  $result = $converter->convertToZGW($xmlContent);
  event(new \CommonGateway\SimTaxToZGWBundle\Events\TaxConversionCompleted($result));
  

• Schema Customization Extend default schemas by overriding config paths:

  'schemas' => [
      'sim_tax' => resource_path('schemas/custom_sim_tax.xsd'),
      'zgw' => resource_path('schemas/custom_zgw.json'),
  ],
  

• Batch Processing Use Laravel queues for large-scale conversions:

  dispatch(new \CommonGateway\SimTaxToZGWBundle\Jobs\ConvertTaxJob($xmlContent, $zgwEndpoint));
  

Gotchas and Tips

Pitfalls

1. Schema Mismatches

   • Issue: XML/JSON may fail validation if schemas are outdated or misconfigured.
   • Fix: Verify schema paths in config/sim_tax_to_zgw.php and update them if needed.
   • Debug: Enable verbose validation:

     $validator->setVerbose(true);
     

2. API Rate Limits

   • Issue: ZGW APIs may throttle requests during batch processing.
   • Fix: Implement retries with exponential backoff:

     use Illuminate\Support\Facades\Http;
     $response = Http::retry(3, 100)->post($endpoint, $data);
     

3. Namespace Collisions

   • Issue: Custom XML namespaces may conflict with default mappings.
   • Fix: Override mappings in config:

     'mappings' => [
         'custom_namespace' => [
             'element' => 'zgw_element',
             'attributes' => ['attr1' => 'zgw_attr'],
         ],
     ],
     

4. Date/Time Formatting

   • Issue: ZGW expects ISO 8601 dates (YYYY-MM-DD), while SimTax may use other formats.
   • Fix: Normalize dates in pre-processing:

     $normalizedXml = preg_replace('/<date>[^-]+-([0-9]{2})-([0-9]{2})-([0-9]{4})<\/date>/', '<date>\3-\1-\2</date>', $xml);
     

Debugging Tips

1. Enable Logging Configure Monolog in config/logging.php to log conversion steps:

   'channels' => [
       'tax_conversion' => [
           'driver' => 'single',
           'path' => storage_path('logs/tax_conversion.log'),
           'level' => 'debug',
       ],
   ],
   

   Then inject the logger:

   $logger = app(\Psr\Log\LoggerInterface::class)->withName('tax_conversion');
   $logger->debug('Conversion started', ['xml_snippet' => substr($xml, 0, 200)]);
   

2. Dump Intermediate Data Use Laravel’s dd() or dump() to inspect objects:

   $mappedData = $converter->mapXmlToZGW($xml);
   dump($mappedData); // Inspect before JSON encoding
   

3. Test with Minimal Payloads Start with a small, valid XML snippet to isolate issues:

   <SimTax xmlns="http://example.com/simtax">
       <BelastingAangifte id="123">
           <Soort>Inkomstenbelasting</Soort>
       </BelastingAangifte>
   </SimTax>
   

Extension Points

1. Custom Converters Extend TaxConverter for domain-specific logic:

   namespace App\Services;
   
   use CommonGateway\SimTaxToZGWBundle\Service\TaxConverter as BaseConverter;
   
   class CustomTaxConverter extends BaseConverter {
       protected function customizeMapping(array $data): array {
           $data['custom_field'] = 'app_specific_value';
           return $data;
       }
   }
   

   Register the service in config/services.php:

   'tax_converter' => App\Services\CustomTaxConverter::class,
   

2. Hooks for Pre/Post Processing Use Laravel’s service provider to bind custom logic:

   public function boot() {
       $this->app->afterResolving(\CommonGateway\SimTaxToZGWBundle\Service\TaxConverter::class, function ($converter) {
           $converter->setPreProcessor(function ($xml) {
               return str_replace('old_value', 'new_value', $xml);
           });
       });
   }
   

3. Schema Validation Extensions Add custom validation rules by extending TaxValidator:

   use CommonGateway\SimTaxToZGWBundle\Validator\TaxValidator;
   
   class ExtendedTaxValidator extends TaxValidator {
       protected function getCustomRules() {
           return [
               'required_field' => 'required|string',
           ];
       }
   }
   

   Bind the validator in the service provider:

   $this->app->bind(\CommonGateway\SimTaxToZGWBundle\Validator\TaxValidator::class, ExtendedTaxValidator::class);