Refactorización para dejar API expuesta limpia. Se cambia cómo funciona XmlDocument (ahora es estándar UTF-8(. Este cambio rompe cosas, pero es un cambio menor. Ahora se debe usar XmlDocument::setEncoding() antes de XmlDocument::saveXml() (o getXml()) sino se indicó (o pudo indicar, como en encoder) el encoding mediante el constructor del XmlDocument.

Author: estebandelaf

src/Contract/XmlDecoderInterface.php

@@ -25,14 +25,9 @@ interface XmlDecoderInterface
      * @param XmlDocumentInterface|DOMElement $documentElement XML document that
      * we want to convert to a PHP array or the element where we will make the
      * conversion if it is not the complete XML document.
-     * @param array|null $data The array where the results will be stored.
-     * @param bool $twinsAsArray Indicates if we should treat twins nodes as an
-     * array.
      * @return array The PHP array with the XML representation.
      */
     public function decode(
-        XmlDocumentInterface|DOMElement $documentElement,
-        ?array &$data = null,
-        bool $twinsAsArray = false
+        XmlDocumentInterface|DOMElement $documentElement
     ): array;
 }

src/Contract/XmlDocumentInterface.php

@@ -22,6 +22,14 @@
  */
 interface XmlDocumentInterface extends DOMDocumentInterface, JsonSerializable
 {
+    /**
+     * Sets the encoding of the XML document.
+     *
+     * @param string $encoding The encoding of the XML document.
+     * @return static
+     */
+    public function setEncoding(string $encoding): static;
+
     /**
      * Returns the name of the root tag of the XML.
      *
@@ -47,9 +55,6 @@ public function getSchema(): ?string;
     /**
      * Loads an XML string into the XML document instance.
      *
-     * Must encode the XML to ISO-8859-1 if is UTF-8 and whas created the
-     * instance with the encoding ISO-8859-1 (default behavior).
-     *
      * @param string $source The string with the XML to load.
      * @param int $options The options for loading the XML.
      * @return bool `true` if the XML was loaded correctly.
@@ -144,9 +149,10 @@ public function getNodes(string $query, array $params = []): DOMNodeList;
      * Queries the XML array using a selector.
      *
      * @param string $selector The selector for the query to the XML array.
+     * @param mixed $default The default value to return if the selector is not found.
      * @return mixed The result of the selector query to the array.
      */
-    public function get(string $selector): mixed;
+    public function get(string $selector, mixed $default = null): mixed;
 
     /**
      * Returns the data of the XML in an array structure.

src/Contract/XmlEncoderInterface.php

@@ -12,8 +12,6 @@
 
 namespace Derafu\Xml\Contract;
 
-use DOMElement;
-
 /**
  * Interface for the class that encodes a PHP array to XML.
  */
@@ -25,17 +23,7 @@ interface XmlEncoderInterface
      *
      * @param array $data The array with the data that will be used to generate
      * XML.
-     * @param array|null $namespace The namespace for the XML (URI and prefix).
-     * @param DOMElement|null $parent The parent element for the nodes, or null
-     * to be the root.
-     * @param XmlDocumentInterface $doc The root XML document that will be
-     * generated.
      * @return XmlDocumentInterface
      */
-    public function encode(
-        array $data,
-        ?array $namespace = null,
-        ?DOMElement $parent = null,
-        ?XmlDocumentInterface $doc = null
-    ): XmlDocumentInterface;
+    public function encode(array $data): XmlDocumentInterface;
 }

src/Service/XmlDecoder.php

@@ -26,29 +26,42 @@ final class XmlDecoder implements XmlDecoderInterface
     /**
      * {@inheritDoc}
      */
-    public function decode(
-        XmlDocumentInterface|DOMElement $documentElement,
-        ?array &$data = null,
-        bool $twinsAsArray = false
-    ): array {
-        // If no tagElement is passed, search one, if not one is obtained, stop
-        // the generation.
+    public function decode(XmlDocumentInterface|DOMElement $documentElement): array
+    {
         $tagElement = $documentElement instanceof DOMElement
             ? $documentElement
             : $documentElement->getDocumentElement()
         ;
+
         if ($tagElement === null) {
             return [];
         }
 
-        // Index in the array that represents the tag. Also it is a shorter
-        // variable name :)
+        $data = [$tagElement->tagName => null];
+
+        $this->decodeNode($tagElement, $data, false);
+
+        return $data;
+    }
+
+    /**
+     * Recursively decodes a DOM element into a PHP array.
+     *
+     * @param DOMElement $tagElement The element to decode.
+     * @param array &$data The array being populated.
+     * @param bool $twinsAsArray Whether to insert children at the current level
+     * instead of nesting them under the element key (used internally when
+     * processing items inside a list of twin nodes).
+     * @return void
+     */
+    private function decodeNode(
+        DOMElement $tagElement,
+        array|null &$data,
+        bool $twinsAsArray,
+    ): void {
         $key = $tagElement->tagName;
 
-        // If there is no destination array for the data, create an array with
-        // the index of the main node with an empty value.
         if ($data === null) {
-            //$data = [$key => self::getEmptyValue()];
             $data = [$key => null];
         }
 
@@ -63,16 +76,13 @@ public function decode(
 
         // If the tagElement has child nodes, add them to the value of the tag.
         if ($tagElement->hasChildNodes()) {
-            self::arrayAddChilds(
+            $this->arrayAddChilds(
                 $data,
                 $tagElement,
                 $tagElement->childNodes,
                 $twinsAsArray
             );
         }
-
-        // Return the data of the XML document as an array.
-        return $data;
     }
 
     /**
@@ -103,19 +113,19 @@ private function arrayAddChilds(
                     } elseif ($childs->length === 1 && empty($data[$key])) {
                         $data[$key] = $textContent;
                     } else {
-                        $array[$key]['@value'] = $textContent;
+                        $data[$key]['@value'] = $textContent;
                     }
                 }
             } elseif ($child instanceof DOMElement) {
-                $n_twinsNodes = self::nodeCountTwins(
+                $n_twinsNodes = $this->nodeCountTwins(
                     $tagElement,
                     $child->tagName
                 );
                 if ($n_twinsNodes === 1) {
                     if ($twinsAsArray) {
-                        self::decode($child, $data);
+                        $this->decodeNode($child, $data, false);
                     } else {
-                        self::decode($child, $data[$key]);
+                        $this->decodeNode($child, $data[$key], false);
                     }
                 } else {
                     // Create a list for the child node, because it has several
@@ -130,13 +140,12 @@ private function arrayAddChilds(
                         $textContent = trim($child->textContent);
                         $data[$key][$child->tagName][] = $textContent;
                     }
-                    // If the child node is scalar, not a list of nodes, it is
-                    // built as if it were a normal array with the call to
-                    // decode().
+                    // If the child node is not scalar, it is built as if it
+                    // were a normal array with the recursive call to decodeNode().
                     else {
                         $nextIndex = count($data[$key][$child->tagName]);
                         $data[$key][$child->tagName][$nextIndex] = [];
-                        self::decode(
+                        $this->decodeNode(
                             $child,
                             $data[$key][$child->tagName][$nextIndex],
                             true

src/Service/XmlEncoder.php

@@ -43,26 +43,28 @@ final class XmlEncoder implements XmlEncoderInterface
     /**
      * {@inheritDoc}
      */
-    public function encode(
-        array $data,
-        ?array $namespace = null,
-        ?DOMElement $parent = null,
-        ?XmlDocumentInterface $doc = null
-    ): XmlDocumentInterface {
-        // If there is no complete XML document (from root, not a node), then
-        // it is created, since it will be needed to create the future nodes.
-        if ($doc === null) {
-            $doc = new XmlDocument();
-        }
+    public function encode(array $data): XmlDocumentInterface
+    {
+        $doc = new XmlDocument();
 
-        // If there is no parent element, then it is being requested to create
-        // the XML document from 0 (from the root node).
-        if ($parent === null) {
-            $parent = $doc;
-        }
+        $this->encodeNode($data, $doc, $doc);
 
-        // Iterate the first level of the array to find the tags that must be
-        // added to the XML document.
+        return $doc;
+    }
+
+    /**
+     * Recursively encodes an array into XML nodes and appends them to a parent.
+     *
+     * @param array $data The array with the data to encode.
+     * @param XmlDocumentInterface $doc The root XML document.
+     * @param DOMNode $parent The parent node to append nodes to.
+     * @return void
+     */
+    private function encodeNode(
+        array $data,
+        XmlDocumentInterface $doc,
+        DOMNode $parent,
+    ): void {
         foreach ($data as $key => $value) {
 
             // If the index is '@attributes' then the value of this index is an
@@ -97,33 +99,18 @@ public function encode(
                 // Only the node is created if it has child nodes. The node will
                 // not be created if an empty array (without children) is passed.
                 if (!empty($value)) {
-                    $this->nodeAddChilds(
-                        $doc,
-                        $parent,
-                        $key,
-                        $value,
-                        $namespace
-                    );
+                    $this->nodeAddChilds($doc, $parent, $key, $value);
                 }
             }
 
             // The node is a scalar (not an array, not child nodes). So the
             // node is created and the value is assigned directly.
             else {
                 if (!$this->skipValue($value)) {
-                    $this->nodeAddValue(
-                        $doc,
-                        $parent,
-                        $key,
-                        (string) $value,
-                        $namespace
-                    );
+                    $this->nodeAddValue($doc, $parent, $key, (string) $value);
                 }
             }
         }
-
-        // Return the generated XML document.
-        return $doc;
     }
 
     /**
@@ -162,7 +149,6 @@ private function nodeAddAttributes(DOMElement $node, array $attributes): void
      * @param DOMNode $parent Node parent to which the child nodes will be added.
      * @param string $tagName Name of the child node tag.
      * @param array $childs Array of data of the child nodes.
-     * @param array|null $namespace XML namespace (URI and prefix).
      * @return void
      * @throws XmlEncoderException If a child node is not an array.
      */
@@ -171,7 +157,6 @@ private function nodeAddChilds(
         DOMNode $parent,
         string $tagName,
         array $childs,
-        ?array $namespace = null,
     ): void {
         $keys = array_keys($childs);
         if (!is_int($keys[0])) {
@@ -196,30 +181,15 @@ private function nodeAddChilds(
                     ));
                 }
 
-                // Add child nodes of the child node (add associative to the
-                // node $tagName).
-                $Node = $namespace
-                    ? $doc->createElementNS(
-                        $namespace[0],
-                        $namespace[1] . ':' . $tagName
-                    )
-                    : $doc->createElement($tagName)
-                ;
+                $Node = $doc->createElement($tagName);
                 $parent->appendChild($Node);
-                $this->encode($child, $namespace, $Node, $doc);
+                $this->encodeNode($child, $doc, $Node);
             }
             // If the child is not an array, it is simply a duplicate node that
             // must be added at the same level as the parent node.
             else {
                 $value = XmlHelper::sanitize((string) $child);
-                $Node = $namespace
-                    ? $doc->createElementNS(
-                        $namespace[0],
-                        $namespace[1] . ':' . $tagName,
-                        $value
-                    )
-                    : $doc->createElement($tagName, $value)
-                ;
+                $Node = $doc->createElement($tagName, $value);
                 $parent->appendChild($Node);
             }
         }
@@ -232,25 +202,16 @@ private function nodeAddChilds(
      * @param DOMNode $parent Node parent to which the node will be added.
      * @param string $tagName Name of the child node tag.
      * @param string $value Value of the child node.
-     * @param array|null $namespace XML namespace (URI and prefix).
      * @return void
      */
     private function nodeAddValue(
         XmlDocumentInterface $doc,
         DOMNode $parent,
         string $tagName,
         string $value,
-        ?array $namespace = null,
     ): void {
         $value = XmlHelper::sanitize($value);
-        $Node = $namespace
-            ? $doc->createElementNS(
-                $namespace[0],
-                $namespace[1] . ':' . $tagName,
-                $value
-            )
-            : $doc->createElement($tagName, $value)
-        ;
+        $Node = $doc->createElement($tagName, $value);
         $parent->appendChild($Node);
     }
 
@@ -268,19 +229,4 @@ private function skipValue(mixed $value): bool
             true
         );
     }
-
-    /**
-     * Checks if a value must generate an empty XML node.
-     *
-     * @param mixed $value Value to check.
-     * @return bool `true` if the value must generate an empty node, `false` otherwise.
-     */
-    // private function createWithEmptyValue(mixed $value): bool
-    // {
-    //     return in_array(
-    //         $value,
-    //         $this->rules['node_values']['generate_empty'],
-    //         true
-    //     );
-    // }
 }