Add XMLConverter::supportsHeader and allow the instance to use header values a cells name

Author: nyamsprod

CHANGELOG.md

@@ -13,6 +13,7 @@ All Notable changes to `Csv` will be documented in this file
 - `ResultSet::createFromRdbms`
 - `RdbmsResult` class to allow converting RDBMS result into `ResultSet`
 - `TabularData` interface
+- `XMLConverter::supportsHeader`
 
 ### Deprecated
 
@@ -30,6 +31,7 @@ All Notable changes to `Csv` will be documented in this file
 - `XMLConverter::$formatter` visibility it should not be public.
 - `XMLConverter` internal rewritten to take advantage of PHP8.4 new dom classes
 - `HTMLConverter` internal rewritten to take advantage of PHP8.4 new dom classes
+- `XMLConverter::fieldElement` now has a `nullable` field element to allow using headers names as cell names.
 
 ### Removed
 

docs/9.0/converter/xml.md

@@ -40,13 +40,25 @@ This method sets the XML record name and optionally the attribute name for the r
 ### XMLConverter::fieldElement
 
 ```php
-public XMLConverter::fieldElement(string $node_name, string $fieldname_attribute_name = ''): self
+public XMLConverter::fieldElement(?string $node_name, string $fieldname_attribute_name = ''): self
 ```
 
-This method sets the XML field name and optionally the attribute name for the field name value.
+This method sets the XML field name and optionally the attribute name for the field name value. If the field name
+is `null` then the converter will use the CSV header names as field name.
 
 <p class="message-info">The default field element name is <code>cell</code>.</p>
 <p class="message-info">The default attribute name is an empty string.</p>
+<p class="message-notice">The field element can be <code>null</code> since version <code>9.22.0</code>.</p>
+
+If the field name is invalid an exception will be thrown. If you opt-in to use the record names as field element name,
+the exception will only be thrown on XML conversion. If you want to check if the CSV current header are usable as
+field name value you can use the new `XMLConverter::supportsHeader` method which returns `false` if at least on
+of the header name is invalid.
+
+```php
+XMLConverter::supportsHeader(['foo', 'bar', '1']);   // returns false
+XMLConverter::supportsHeader(['foo', 'bar', 'foo']); // returns true
+```
 
 ### XMLConverter::formatter
 

src/HTMLConverter.php

@@ -47,13 +47,6 @@ public static function create(): self
         return new self();
     }
 
-    /**
-     * DEPRECATION WARNING! This method will be removed in the next major point release.
-     *
-     * @throws DOMException
-     * @see HTMLConverter::create()
-     * @deprecated since version 9.7.0
-     */
     public function __construct()
     {
     }

src/XMLConverter.php

@@ -22,6 +22,7 @@
 use DOMException;
 use Exception;
 use RuntimeException;
+use Throwable;
 use ValueError;
 
 use function class_exists;
@@ -40,7 +41,7 @@ class XMLConverter
     /** XML Node name. */
     protected string $record_name = 'row';
     /** XML Item name. */
-    protected string $field_name = 'cell';
+    protected ?string $field_name = 'cell';
     /** XML column attribute name. */
     protected string $column_attr = '';
     /** XML offset attribute name. */
@@ -68,12 +69,6 @@ public static function create(): self
         return new self();
     }
 
-    /**
-     * DEPRECATION WARNING! This method will be removed in the next major point release.
-     *
-     * @deprecated since version 9.7.0
-     * @see XMLConverter::create()
-     */
     public function __construct()
     {
     }
@@ -86,7 +81,7 @@ public function __construct()
     public function rootElement(string $node_name): self
     {
         $clone = clone $this;
-        $clone->root_name = $this->filterElementName($node_name);
+        $clone->root_name = (string) $this->filterElementName($node_name);
 
         return $clone;
     }
@@ -99,7 +94,7 @@ public function rootElement(string $node_name): self
     public function recordElement(string $node_name, string $record_offset_attribute_name = ''): self
     {
         $clone = clone $this;
-        $clone->record_name = $this->filterElementName($node_name);
+        $clone->record_name = (string) $this->filterElementName($node_name);
         $clone->offset_attr = $this->filterAttributeName($record_offset_attribute_name);
 
         return $clone;
@@ -110,7 +105,7 @@ public function recordElement(string $node_name, string $record_offset_attribute
      *
      * @throws DOMException
      */
-    public function fieldElement(string $node_name, string $fieldname_attribute_name = ''): self
+    public function fieldElement(?string $node_name, string $fieldname_attribute_name = ''): self
     {
         $clone = clone $this;
         $clone->field_name = $this->filterElementName($node_name);
@@ -203,11 +198,12 @@ protected function recordToElement(DOMDocument|XMLDocument $document, array $rec
      */
     protected function fieldToElement(DOMDocument|XMLDocument $document, string $value, int|string $node_name): DOMElement|Element
     {
-        $item = $document->createElement($this->field_name);
+        $node_name = (string) $node_name;
+        $item = $document->createElement($this->field_name ?? $node_name);
         $item->appendChild($document->createTextNode($value));
 
         if ('' !== $this->column_attr) {
-            $item->setAttribute($this->column_attr, (string) $node_name);
+            $item->setAttribute($this->column_attr, $node_name);
         }
 
         return $item;
@@ -218,8 +214,12 @@ protected function fieldToElement(DOMDocument|XMLDocument $document, string $val
      *
      * @throws DOMException If the Element name is invalid
      */
-    protected function filterElementName(string $value): string
+    protected function filterElementName(?string $value): ?string
     {
+        if (null === $value) {
+            return null;
+        }
+
         return self::newXmlDocument(XMLDocument::class)->createElement($value)->tagName;
     }
 
@@ -259,4 +259,18 @@ public function convert(iterable $records): DOMDocument
 
         return $document;
     }
+
+    public static function supportsHeader(array $header): bool
+    {
+        $document = self::newXmlDocument(XMLDocument::class);
+        foreach ($header as $header_value) {
+            try {
+                $res = $document->createElement($header_value)->tagName;
+            } catch (Throwable) {
+                return false;
+            }
+        }
+
+        return [] !== $header;
+    }
 }

src/XMLConverterTest.php

@@ -16,8 +16,11 @@
 use Dom\XMLDocument;
 use DOMDocument;
 use DOMException;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
+use Throwable;
 
 use function array_map;
 use function class_exists;
@@ -145,4 +148,64 @@ public function testToXMLWithFormatter(): void
 
         self::assertStringContainsString('ABEL', (string) $dom->saveXML());
     }
+
+    #[Test]
+    public function it_can_use_the_document_header_as_cell_name(): void
+    {
+        $csv = Reader::createFromPath(__DIR__.'/../test_files/prenoms.csv', 'r')
+            ->setDelimiter(';')
+            ->setHeaderOffset(0)
+            ->slice(0, 2);
+
+        $converter = XMLConverter::create()
+            ->rootElement('stats')
+            ->recordElement('per_name', 'offset')
+            ->fieldElement(null);
+
+        /** @var DOMDocument|XMLDocument $dom */
+        $dom = class_exists(XMLDocument::class) ? XMLDocument::createEmpty() : new DOMDocument(encoding: 'UTF-8');
+        $dom->appendChild($converter->import($csv, $dom));
+        $dom->formatOutput = true;
+
+        $generatedXml = (string) $dom->saveXML();
+
+        self::assertStringContainsString('<per_name offset="1">', $generatedXml);
+        self::assertStringContainsString('<nombre>55</nombre>', $generatedXml);
+        self::assertStringContainsString('<sexe>M</sexe>', $generatedXml);
+        self::assertStringContainsString('<annee>2004</annee>', $generatedXml);
+    }
+
+    #[Test]
+    public function it_will_trigger_an_exception_if_the_header_is_invalid(): void
+    {
+        $csv = Reader::createFromPath(__DIR__.'/../test_files/prenoms.csv', 'r')
+            ->setDelimiter(';')
+            ->slice(0, 2);
+
+        $converter = XMLConverter::create()
+            ->rootElement('stats')
+            ->recordElement('per_name', 'offset')
+            ->fieldElement(null);
+
+        /** @var DOMDocument|XMLDocument $dom */
+        $dom = class_exists(XMLDocument::class) ? XMLDocument::createEmpty() : new DOMDocument(encoding: 'UTF-8');
+
+        $this->expectException(Throwable::class);
+        $converter->import($csv, $dom);
+    }
+
+    #[Test]
+    #[DataProvider('provideHeader')]
+    public function it_will_tell_if_it_can_use_a_specific_header(array $header, bool $expected): void
+    {
+        self::assertSame($expected, XMLConverter::supportsHeader($header));
+    }
+
+    public static function provideHeader(): iterable
+    {
+        yield 'no header' => ['header' => [], 'expected' => false];
+        yield 'header with name value' => ['header' => ['foo', 'bar'], 'expected' => true];
+        yield 'header with numeric index' => ['header' => [1, 'bar'], 'expected' => false];
+        yield 'header with string as numeric index' => ['header' => ['1', 'bar'], 'expected' => false];
+    }
 }