Xml Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ajtis/xml-bundle
   

   Register the bundle in config/bundles.php (Laravel) or AppKernel.php (Symfony):

   // config/bundles.php
   return [
       // ...
       Ajtis\XmlBundle\XmlBundle::class => ['all' => true],
   ];
   

2. First Use Case: Convert an array to XML (simplest form):

   use Ajtis\XmlBundle\Model\XmlGenerator;
   
   $generator = new XmlGenerator();
   $xml = $generator->generateFromArray(['root' => ['child' => 'value']]);
   

3. Where to Look First:

   • Documentation: Check vendor/ajtis/xml-bundle/docs/ for usage examples.
   • Services: The bundle provides DIC services (xml_generator, xml_reader, xml_prepare).
   • Examples: Refer to the Usage section in the README for common patterns.

Implementation Patterns

Core Workflows

1. Array-to-XML Conversion:

   • Use XmlGenerator for structured XML output with attributes, namespaces, and values.
   • Example:

     $params = [
         'Request' => [
             '@attrib' => ['Id' => 123],
             'Data' => ['@value' => 'content']
         ]
     ];
     $xml = $generator->generateFromArray($params);
     

2. XML-to-Array Parsing:

   • Use XmlReader to parse XML strings into associative arrays.
   • Example:

     $xmlString = '<root><item>value</item></root>';
     $array = $reader->processConvert($xmlString);
     

3. Preparing Data:

   • Use XmlPrepare to sanitize arrays before conversion (e.g., flattening or cleaning keys).
   • Example:

     $prepared = $prepare->prepareArrayBeforeToXmlConvert($rawArray);
     $xml = $generator->generateFromArray($prepared);
     

Integration Tips

• Laravel Service Providers: Bind the bundle’s services to Laravel’s container in AppServiceProvider:

  public function register()
  {
      $this->app->bind('xml_generator', function ($app) {
          return new \Ajtis\XmlBundle\Model\XmlGenerator();
      });
  }
  

• API Responses: Use the bundle to generate XML responses for legacy systems:

  return response($generator->generateFromArray($data))->header('Content-Type', 'application/xml');
  

• Configuration: Extend the bundle’s behavior via dependency injection (e.g., custom namespace handlers).

Gotchas and Tips

Pitfalls

1. Namespace Handling:

   • Incorrect namespace URIs (e.g., http// vs. http://) will break XML validation.
   • Fix: Validate URIs manually or use a library like Symfony\Component\Validator\Constraints\Url.

2. Attribute vs. Value Confusion:

   • Keys prefixed with @attrib define attributes, while @value defines text content.
   • Gotcha: Forgetting @value will omit text nodes in the output.

3. Root Node Defaults:

   • The bundle auto-wraps output in a <root> tag. Use setRootName() to customize:

     $generator->setRootName('api_response');
     

4. XML Declaration:

   • The bundle always includes <?xml version="1.0" encoding="UTF-8"?>.
   • Workaround: Post-process the string to remove it if needed.

Debugging Tips

• Validate XML: Use SimpleXMLElement to debug malformed XML:

  $xml = simplexml_load_string($generatedXml);
  if ($xml === false) {
      throw new \RuntimeException('Invalid XML: ' . libxml_get_last_error());
  }
  

• Logging: Enable Symfony’s profiler (APP_DEBUG=true) to inspect service calls.

Extension Points

1. Custom Generators: Extend XmlGenerator to add domain-specific logic:

   class CustomXmlGenerator extends XmlGenerator {
       public function generateWithCustomLogic(array $data) {
           // Pre-process data
           return parent::generateFromArray($data);
       }
   }
   

2. Event Listeners: Hook into the bundle’s lifecycle (if it supports events) to modify XML generation dynamically.

3. Configuration Overrides: Override default settings via bundle configuration (check config/packages/ajtis_xml.yaml if available).

Performance Notes

• For large XML payloads, stream the output instead of building the entire string in memory:

  $generator->setStreaming(true);