Simplify XMLConverter codebase to reduce BC break

Author: nyamsprod

docs/9.0/converter/xml.md

@@ -7,6 +7,9 @@ title: Converting a CSV into a XML DOMDocument object
 
 The `XMLConverter` converts a CSV records collection into a PHP `DOMDocument`.
 
+<p class="message-info">Starting with version <code>9.22.0</code>, support for
+returning <code>\Dom\XmlDocument</code> instances is added</p>
+
 ## Settings
 
 Prior to converting your records collection into XML, you may wish to configure the element and its associated attribute names. To do so, `XMLConverter` provides methods to set up these settings.
@@ -57,10 +60,23 @@ This method allow to apply a callback prior to converting your collection indivi
 This callback allows you to specify how each item will be converted. The formatter should
 return an associative array suitable for conversion.
 
+### XMLConverter::xmlClass
+
+<p class="message-info">New feature introduced in version <code>9.22.0</code></p>
+
+```php
+public XMLConverter::xmlClass(string $xmlClass): self
+```
+
+This method allow to specify the return type when calling the `convert` method.
+The accepted values are `DomDocument` or `Dom\XmlDocument` class names any other
+value will trigger a `ValueError` from the API. To avoid BC break the default
+value if this method is **NEVER** call is `DomDocument`.
+
 ## Conversion
 
 ```php
-public XMLConverter::convert(iterable $records): DOMDocument
+public XMLConverter::convert(iterable $records): DOMDocument|\Dom\XmlDocument
 ```
 
 The `XMLConverter::convert` accepts an `iterable` which represents the records collection and returns a `DOMDocument` object.
@@ -120,7 +136,7 @@ echo htmlentities($dom->saveXML());
 <p class="message-info">New feature introduced in version <code>9.3.0</code></p>
 
 ```php
-public XMLConverter::import(iterable $records, DOMDocument $doc): DOMElement
+public XMLConverter::import(iterable $records, DOMDocument|\Dom\XMLDocument $doc): DOMElement|\Dom\Element
 ```
 
 Instead of converting your tabular data into a full XML document you can now import it into an already existing `DOMDocument` object.
@@ -129,7 +145,7 @@ To do so, you need to specify which document the data should be imported into us
 This method takes two arguments:
 
 - the tabular data as defined for the `XMLConverter::convert` method;
-- a `DOMDocument` object to import the data into;
+- a `DOMDocument` or a `\Dom\XmlDocument` object to import the data into;
 
 Note that the resulting `DOMElement` is attached to the given `DOMDocument` object but not yet included in the document tree.
 To include it, you still need to call a DOM insertion method like `appendChild` or `insertBefore` with a node that *is* currently in the document tree.

src/HTMLConverterTest.php

@@ -29,12 +29,10 @@ public function testToHTML(): void
             ->setHeaderOffset(0)
         ;
 
-        $stmt = Statement::create()
+        $records = Statement::create()
             ->offset(3)
             ->limit(5)
-        ;
-
-        $records = $stmt->process($csv);
+            ->process($csv);
 
         $converter = HTMLConverter::create()
             ->table('table-csv-data', 'test')
@@ -58,12 +56,10 @@ public function testToHTMLWithTHeadTableSection(): void
             ->setHeaderOffset(0)
         ;
 
-        $stmt = Statement::create()
+        $records = Statement::create()
             ->offset(3)
             ->limit(5)
-        ;
-
-        $records = $stmt->process($csv);
+            ->process($csv);
 
         $converter = HTMLConverter::create()
             ->table('table-csv-data', 'test')
@@ -89,12 +85,10 @@ public function testToHTMLWithTFootTableSection(): void
             ->setHeaderOffset(0)
         ;
 
-        $stmt = Statement::create()
+        $records = Statement::create()
             ->offset(3)
             ->limit(5)
-        ;
-
-        $records = $stmt->process($csv);
+            ->process($csv);
 
         $converter = HTMLConverter::create()
             ->table('table-csv-data', 'test')
@@ -120,12 +114,10 @@ public function testToHTMLWithBothTableHeaderSection(): void
             ->setHeaderOffset(0)
         ;
 
-        $stmt = Statement::create()
+        $records = Statement::create()
             ->offset(3)
             ->limit(5)
-        ;
-
-        $records = $stmt->process($csv);
+            ->process($csv);
 
         $converter = HTMLConverter::create()
             ->table('table-csv-data', 'test')
@@ -154,24 +146,19 @@ public function testToHTMLWithFormatter(): void
     {
         $csv = Reader::createFromPath(__DIR__.'/../test_files/prenoms.csv', 'r')
             ->setDelimiter(';')
-            ->setHeaderOffset(0)
-        ;
+            ->setHeaderOffset(0);
 
-        $stmt = Statement::create()
+        $records = Statement::create()
             ->offset(3)
             ->limit(5)
-        ;
-
-        $records = $stmt->process($csv);
+            ->process($csv);
 
         $converter = HTMLConverter::create()
             ->table('table-csv-data', 'test')
             ->td('title')
             ->tr('data-record-offset')
             ->formatter(fn (array $record, int|string $key): array => array_map(strtoupper(...), $record));
-        ;
 
-        $html = $converter->convert($records);
-        self::assertStringContainsString('ABEL', $html);
+        self::assertStringContainsString('ABEL', $converter->convert($records));
     }
 }

src/XMLConverter.php

@@ -20,9 +20,12 @@
 use DOMElement;
 use DOMException;
 use Exception;
+use RuntimeException;
+use ValueError;
 
 use function class_exists;
 use function extension_loaded;
+use function in_array;
 
 /**
  * Converts tabular data into a DOMDocument object.
@@ -41,10 +44,23 @@ class XMLConverter
     protected string $offset_attr = '';
     /** @var ?Closure(array, array-key): array */
     protected ?Closure $formatter = null;
+    /** @var class-string */
+    protected string $xmlClass = DomDocument::class;
 
-    private static function supportsModerDom(): bool
+    /**
+     * @param class-string $xmlClass
+     *
+     * @throws RuntimeException If the extension is not present
+     * @throws ValueError If the XML class used is invalid
+     */
+    private static function newXmlDocument(string $xmlClass = DOMDocument::class): DOMDocument|XMLDocument
     {
-        return extension_loaded('dom') && class_exists(XMLDocument::class);
+        return match (true) {
+            !extension_loaded('dom') => throw new RuntimeException('The DOM extension is not loaded.'),
+            !in_array($xmlClass, [XMLDocument::class , DOMDocument::class], true) => throw new ValueError('The xml class is invalid.'),
+            XMLDocument::class === $xmlClass && class_exists(XMLDocument::class) => XMLDocument::createEmpty(),
+            default => new DOMDocument(encoding: 'UTF-8'),
+        };
     }
 
     public static function create(): self
@@ -67,15 +83,10 @@ public function __construct()
      */
     public function convert(iterable $records): DOMDocument|XMLDocument
     {
-        if (null !== $this->formatter) {
-            $records = MapIterator::fromIterable($records, $this->formatter);
-        }
+        $document = self::newXmlDocument($this->xmlClass);
+        $document->appendChild($this->import($records, $document));
 
-        $doc = self::supportsModerDom() ? XMLDocument::createEmpty() : new DOMDocument(version:'1.0', encoding:'UTF-8');
-        $node = $this->import($records, $doc);
-        $doc->appendChild($node);
-
-        return $doc;
+        return $document;
     }
 
     /**
@@ -111,6 +122,10 @@ public function download(iterable $records, ?string $filename = null, string $en
      */
     public function import(iterable $records, DOMDocument|XMLDocument $doc): DOMElement|Element
     {
+        if (null !== $this->formatter) {
+            $records = MapIterator::fromIterable($records, $this->formatter);
+        }
+
         $root = $doc->createElement($this->root_name);
         foreach ($records as $offset => $record) {
             $root->appendChild($this->recordToElement($doc, $record, $offset));
@@ -123,12 +138,11 @@ public function import(iterable $records, DOMDocument|XMLDocument $doc): DOMElem
      * Converts a CSV record into a DOMElement and
      * adds its offset as DOMElement attribute.
      */
-    protected function recordToElement(DOMDocument|XMLDocument $doc, array $record, int $offset): DOMElement|Element
+    protected function recordToElement(DOMDocument|XMLDocument $document, array $record, int $offset): DOMElement|Element
     {
-        $node = $doc->createElement($this->record_name);
+        $node = $document->createElement($this->record_name);
         foreach ($record as $node_name => $value) {
-            $item = $this->fieldToElement($doc, (string) $value, $node_name);
-            $node->appendChild($item);
+            $node->appendChild($this->fieldToElement($document, (string) $value, $node_name));
         }
 
         if ('' !== $this->offset_attr) {
@@ -144,10 +158,10 @@ protected function recordToElement(DOMDocument|XMLDocument $doc, array $record,
      * Converts the CSV item into a DOMElement and adds the item offset
      * as attribute to the returned DOMElement
      */
-    protected function fieldToElement(DOMDocument|XMLDocument $doc, string $value, int|string $node_name): DOMElement|Element
+    protected function fieldToElement(DOMDocument|XMLDocument $document, string $value, int|string $node_name): DOMElement|Element
     {
-        $item = $doc->createElement($this->field_name);
-        $item->appendChild($doc->createTextNode($value));
+        $item = $document->createElement($this->field_name);
+        $item->appendChild($document->createTextNode($value));
 
         if ('' !== $this->column_attr) {
             $item->setAttribute($this->column_attr, (string) $node_name);
@@ -183,31 +197,62 @@ public function formatter(?callable $formatter): self
     }
 
     /**
-     * Filters XML element name.
+     * XML Record element setter.
      *
-     * @throws DOMException If the Element name is invalid
+     * @throws DOMException
      */
-    protected function filterElementName(string $value): string
+    public function recordElement(string $node_name, string $record_offset_attribute_name = ''): self
     {
-        $document = self::supportsModerDom() ? XmlDocument::createEmpty() : new DOMDocument('1.0');
+        $clone = clone $this;
+        $clone->record_name = $this->filterElementName($node_name);
+        $clone->offset_attr = $this->filterAttributeName($record_offset_attribute_name);
 
-        return $document->createElement($value)->tagName;
+        return $clone;
     }
 
     /**
-     * XML Record element setter.
+     * XML Field element setter.
      *
      * @throws DOMException
      */
-    public function recordElement(string $node_name, string $record_offset_attribute_name = ''): self
+    public function fieldElement(string $node_name, string $fieldname_attribute_name = ''): self
     {
         $clone = clone $this;
-        $clone->record_name = $this->filterElementName($node_name);
-        $clone->offset_attr = $this->filterAttributeName($record_offset_attribute_name);
+        $clone->field_name = $this->filterElementName($node_name);
+        $clone->column_attr = $this->filterAttributeName($fieldname_attribute_name);
+
+        return $clone;
+    }
+
+    /**
+     * @param class-string $xmlClass
+     */
+    public function xmlClass(string $xmlClass): self
+    {
+        if (!in_array($xmlClass, [XMLDocument::class , DOMDocument::class], true)) {
+            throw new ValueError('The xml class is invalid.');
+        }
+
+        if ($this->xmlClass === $xmlClass) {
+            return $this;
+        }
+
+        $clone = clone $this;
+        $clone->xmlClass = $xmlClass;
 
         return $clone;
     }
 
+    /**
+     * Filters XML element name.
+     *
+     * @throws DOMException If the Element name is invalid
+     */
+    protected function filterElementName(string $value): string
+    {
+        return self::newXmlDocument(XMLDocument::class)->createElement($value)->tagName;
+    }
+
     /**
      * Filters XML attribute name.
      *
@@ -221,24 +266,9 @@ protected function filterAttributeName(string $value): string
             return $value;
         }
 
-        $document = self::supportsModerDom() ? XmlDocument::createEmpty() : new DOMDocument('1.0');
-        $element = $document->createElement('foo');
+        $element = self::newXmlDocument(XMLDocument::class)->createElement('foo');
         $element->setAttribute($value, 'foo');
 
         return $value;
     }
-
-    /**
-     * XML Field element setter.
-     *
-     * @throws DOMException
-     */
-    public function fieldElement(string $node_name, string $fieldname_attribute_name = ''): self
-    {
-        $clone = clone $this;
-        $clone->field_name = $this->filterElementName($node_name);
-        $clone->column_attr = $this->filterAttributeName($fieldname_attribute_name);
-
-        return $clone;
-    }
 }

src/XMLConverterTest.php

@@ -13,13 +13,14 @@
 
 namespace League\Csv;
 
+use Dom\XMLDocument;
 use DOMDocument;
-use DOMElement;
 use DOMException;
 use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\TestCase;
 
 use function array_map;
+use function class_exists;
 
 #[Group('converter')]
 final class XMLConverterTest extends TestCase
@@ -44,24 +45,19 @@ public function testToXML(): void
             ->fieldElement('field', 'name')
         ;
 
-        $dom = $converter->convert($records);
+        $dom = $converter->convert($records, XMLDocument::class);
         $record_list = $dom->getElementsByTagName('record');
-
-        /** @var DOMElement $record_node */
         $record_node = $record_list->item(0);
-
         $field_list = $dom->getElementsByTagName('field');
-
-        /** @var DOMElement $field_node */
         $field_node = $field_list->item(0);
 
-        /** @var DOMElement $baseTag */
-        $baseTag = $dom->documentElement;
-
-        self::assertSame('csv', $baseTag->tagName);
+        self::assertNotNull($dom->documentElement);
+        self::assertSame('csv', $dom->documentElement->tagName);
         self::assertEquals(5, $record_list->length);
+        self::assertNotNull($record_node);
         self::assertTrue($record_node->hasAttribute('offset'));
         self::assertEquals(20, $field_list->length);
+        self::assertNotNull($field_node);
         self::assertTrue($field_node->hasAttribute('name'));
     }
 
@@ -93,7 +89,7 @@ public function testImport(): void
             ->fieldElement('field', 'name')
         ;
 
-        $doc = new DOMDocument('1.0');
+        $doc = class_exists(XMLDocument::class) ? XMLDocument::createEmpty() : new DOMDocument('1.0');
         $element = $converter->import($records, $doc);
 
         self::assertCount(0, $doc->childNodes);