Xml Common Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require simplesamlphp/xml-common
   

   No additional configuration is required for basic usage.

2. First Use Case: Parsing XML Import the core SimpleXMLElement wrapper (if needed) or use the package’s utility classes directly:

   use simplesaml\xml\XML;
   use simplesaml\xml\XMLParser;
   
   // Parse XML string
   $xmlString = '<root><child>value</child></root>';
   $xml = XMLParser::parseString($xmlString);
   
   // Access elements
   $childValue = $xml->child->__toString();
   

3. Where to Look First

   • simplesaml\xml\XML: Core class for XML manipulation.
   • simplesaml\xml\XMLParser: Handles parsing XML strings/files.
   • simplesaml\xml\XMLWriter: For generating XML output.
   • simplesaml\xml\XMLUtils: Utility methods (e.g., namespacing, validation).

Implementation Patterns

Common Workflows

1. XML Parsing and Traversal Use XMLParser to load XML from strings or files, then traverse the DOM-like structure:

   $xml = XMLParser::parseFile('config.xml');
   foreach ($xml->children() as $child) {
       echo $child->getName() . ': ' . $child->__toString();
   }
   

2. Generating XML Build XML dynamically with XMLWriter:

   $writer = new XMLWriter();
   $writer->startDocument('1.0', 'UTF-8');
   $writer->startElement('root');
   $writer->writeElement('child', 'value');
   $writer->endElement();
   $writer->endDocument();
   echo $writer->outputMemory();
   

3. Namespaced XML Handle namespaces explicitly:

   $xml = XMLParser::parseString('<ns:root xmlns:ns="urn:test">...</ns:root>');
   $ns = $xml->getNamespaces();
   $root = $xml->children($ns['ns']);
   

4. Validation Use XMLUtils::validate() to check XML against a schema (if supported):

   $isValid = XMLUtils::validate($xmlString, 'schema.xsd');
   

Integration Tips

• Laravel Service Providers Bind the parser/writer to the container for dependency injection:

  $this->app->bind(XMLParser::class, function () {
      return new XMLParser();
  });
  

• Form Requests Parse XML payloads in Laravel requests:

  public function store(Request $request) {
      $xml = XMLParser::parseString($request->xml);
      // Process $xml...
  }
  

• API Responses Return XML responses using XMLWriter:

  return response(XMLWriter::generate($data), 200, ['Content-Type' => 'application/xml']);
  

Gotchas and Tips

Pitfalls

1. Namespace Handling

   • Forgetting to register namespaces when parsing can lead to silent failures.
   • Fix: Always check $xml->getNamespaces() and use children($namespace) explicitly.

2. Memory Limits

   • Parsing large XML files may hit PHP’s memory_limit.
   • Fix: Use XMLReader (not part of this package) for streaming large files.

3. Case Sensitivity

   • XML tags are case-sensitive. Mismatched cases (e.g., <Root> vs <root>) will fail.
   • Fix: Normalize tags before comparison:

     $tagName = strtolower($xml->getName());
     

4. Deprecated Methods

   • Some methods (e.g., DOM-like access) may behave unexpectedly.
   • Fix: Prefer XMLUtils or the XML class’s documented methods.

Debugging Tips

• Dump XML Structure Use var_dump($xml->asXML()) or print_r($xml->children()) to inspect the parsed structure.

• Enable Error Reporting Configure simplesaml\xml\XMLParser to throw exceptions on errors:

  $parser = new XMLParser();
  $parser->setThrowExceptions(true);
  

Extension Points

1. Custom XML Writers Extend XMLWriter to add domain-specific elements:

   class CustomXMLWriter extends XMLWriter {
       public function writeUser($user) {
           $this->startElement('user');
           $this->writeElement('id', $user->id);
           $this->endElement();
       }
   }
   

2. Schema Validation Integrate with libxml for XSD validation:

   libxml_use_internal_errors(true);
   $doc = new DOMDocument();
   $doc->loadXML($xmlString);
   if ($doc->schemaValidate('schema.xsd')) {
       // Valid
   }
   

3. Laravel Facades Create a facade for cleaner syntax:

   // app/Facades/XML.php
   namespace App\Facades;
   use Illuminate\Support\Facades\Facade;
   class XML extends Facade {
       protected static function getFacadeAccessor() {
           return 'xml.parser';
       }
   }
   

   Bind in a service provider:

   $this->app->bind('xml.parser', function () {
       return new XMLParser();
   });
   

   Usage:

   $xml = XML::parseString($string);