Xml Common Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer (now compatible with PHP 8.4+):

   composer require simplesamlphp/xml-common
   

   No additional configuration is required for basic usage, but ensure your project uses PHP 8.4+ for full compatibility.

2. First Use Case: Parsing XML Import the core classes and leverage the updated DOM-API (PHP 8.4+):

   use simplesaml\xml\XML;
   use simplesaml\xml\XMLParser;
   
   // Parse XML string (now using PHP 8.4's DOM-API under the hood)
   $xmlString = '<root><child>value</child></root>';
   $xml = XMLParser::parseString($xmlString);
   
   // Access elements (note: DOM-API methods may differ from older versions)
   $childValue = $xml->child->textContent; // Updated property access
   

3. Where to Look First

   • simplesaml\xml\XML: Core class for XML manipulation (now aligned with PHP 8.4's DOM-API).
   • simplesaml\xml\XMLParser: Handles parsing XML strings/files (updated for PHP 8.4 compatibility).
   • simplesaml\xml\XMLWriter: For generating XML output (unchanged, but now leverages PHP 8.5's URI-component).
   • simplesaml\xml\XMLUtils: Utility methods (e.g., namespacing, validation) with minor adjustments for PHP 8.4+.

Implementation Patterns

Common Workflows

1. XML Parsing and Traversal (PHP 8.4+ DOM-API) Use XMLParser with the updated DOM-API methods:

   $xml = XMLParser::parseFile('config.xml');
   foreach ($xml->children as $child) { // Note: `children` is now a property, not a method
       echo $child->nodeName . ': ' . $child->textContent;
   }
   

2. Generating XML Build XML dynamically with XMLWriter (unchanged, but now uses PHP 8.5's URI-component):

   $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 (unchanged, but ensure PHP 8.4+ compatibility):

   $xml = XMLParser::parseString('<ns:root xmlns:ns="urn:test">...</ns:root>');
   $ns = $xml->lookupNamespaceURI('ns'); // Updated method (PHP 8.4+ DOM-API)
   $root = $xml->children($ns);
   

4. Validation Use XMLUtils::validate() (unchanged, but validate against PHP 8.4+):

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

Integration Tips

• Laravel Service Providers Bind the parser/writer to the container (unchanged, but ensure PHP 8.4+):

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

• Form Requests Parse XML payloads in Laravel requests (unchanged):

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

• API Responses Return XML responses using XMLWriter (unchanged):

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

Gotchas and Tips

Pitfalls

1. DOM-API Migration (PHP 8.4+)

   • The package now uses PHP 8.4's DOM-API, which may break older code relying on deprecated methods (e.g., children() as a method instead of a property).
   • Fix: Update your code to use the new DOM-API properties/methods:

     // Old (deprecated):
     $children = $xml->children(); // Method call
     
     // New (PHP 8.4+):
     $children = $xml->children; // Property access
     

2. Namespace Handling (Updated Methods)

   • getNamespaces() is replaced with lookupNamespaceURI() in PHP 8.4+.
   • Fix: Update namespace lookups:

     // Old:
     $ns = $xml->getNamespaces();
     
     // New:
     $ns = $xml->lookupNamespaceURI('prefix');
     

3. PHP Version Requirements

   • This package requires PHP 8.4+. Attempting to use it on older versions will fail.
   • Fix: Update your PHP version or use a compatible older release of the package.

4. Guzzle Dependency Removed

   • The package no longer depends on Guzzle (replaced by PHP 8.5's URI-component). If your project extends this library, remove Guzzle dependencies.

Debugging Tips

• Dump XML Structure Use var_dump($xml->ownerDocument) or print_r($xml->childNodes) to inspect the parsed structure (PHP 8.4+ DOM-API).

• Enable Error Reporting Configure XMLParser to throw exceptions on errors (unchanged):

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

Extension Points

1. Custom XML Writers Extend XMLWriter to add domain-specific elements (unchanged, but ensure PHP 8.4+ compatibility):

   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 (unchanged, but validate against PHP 8.4+):

   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 (unchanged, but ensure PHP 8.4+):

   // 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 (unchanged):

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

   Usage (unchanged):

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