Se refactoriza para dejar una biblioteca estándar de XML, sin hacks por codificación.

Author: estebandelaf

src/Exception/XmlEncoderException.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Derafu: XML - Library for XML manipulation.
+ *
+ * Copyright (c) 2026 Esteban De La Fuente Rubio / Derafu <https://www.derafu.dev>
+ * Licensed under the MIT License.
+ * See LICENSE file for more details.
+ */
+
+namespace Derafu\Xml\Exception;
+
+/**
+ * Exception thrown when a PHP array cannot be encoded into XML.
+ *
+ * Covers two cases:
+ *   - An attribute value is an array (attributes must be scalar).
+ *   - A child node contains a non-associative array where an associative
+ *     one is required.
+ */
+class XmlEncoderException extends XmlException
+{
+}

src/Exception/XmlParseException.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Derafu: XML - Library for XML manipulation.
+ *
+ * Copyright (c) 2026 Esteban De La Fuente Rubio / Derafu <https://www.derafu.dev>
+ * Licensed under the MIT License.
+ * See LICENSE file for more details.
+ */
+
+namespace Derafu\Xml\Exception;
+
+/**
+ * Exception thrown when an XML string cannot be parsed.
+ *
+ * Covers two cases:
+ *   - The XML string is empty.
+ *   - The XML string is malformed (libxml parse error).
+ */
+class XmlParseException extends XmlException
+{
+}

src/Exception/XmlQueryException.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Derafu: XML - Library for XML manipulation.
+ *
+ * Copyright (c) 2026 Esteban De La Fuente Rubio / Derafu <https://www.derafu.dev>
+ * Licensed under the MIT License.
+ * See LICENSE file for more details.
+ */
+
+namespace Derafu\Xml\Exception;
+
+/**
+ * Exception thrown when an XPath query fails.
+ *
+ * Covers two cases:
+ *   - The XPath expression is syntactically invalid.
+ *   - The XPath expression points to a node that does not exist (when the
+ *     node is required).
+ */
+class XmlQueryException extends XmlException
+{
+}

src/Service/XmlEncoder.php

@@ -14,11 +14,11 @@
 
 use Derafu\Xml\Contract\XmlDocumentInterface;
 use Derafu\Xml\Contract\XmlEncoderInterface;
+use Derafu\Xml\Exception\XmlEncoderException;
 use Derafu\Xml\XmlDocument;
 use Derafu\Xml\XmlHelper;
 use DOMElement;
 use DOMNode;
-use InvalidArgumentException;
 
 /**
  * Class that creates an XML document from a PHP array.
@@ -132,14 +132,14 @@ public function encode(
      * @param DOMElement $node Node to which the attributes will be added.
      * @param array $attributes Array of attributes (key => value).
      * @return void
-     * @throws InvalidArgumentException If an attribute value is an array.
+     * @throws XmlEncoderException If an attribute value is an array.
      */
     private function nodeAddAttributes(DOMElement $node, array $attributes): void
     {
         foreach ($attributes as $attribute => $value) {
             // If the attribute value is an array, it cannot be assigned.
             if (is_array($value)) {
-                throw new InvalidArgumentException(sprintf(
+                throw new XmlEncoderException(sprintf(
                     'The type of data of the value entered for the attribute "%s" of the node "%s" is incorrect (cannot be an array). The value is: %s',
                     $attribute,
                     $node->tagName,
@@ -164,7 +164,7 @@ private function nodeAddAttributes(DOMElement $node, array $attributes): void
      * @param array $childs Array of data of the child nodes.
      * @param array|null $namespace XML namespace (URI and prefix).
      * @return void
-     * @throws InvalidArgumentException If a child node is not an array.
+     * @throws XmlEncoderException If a child node is not an array.
      */
     private function nodeAddChilds(
         XmlDocumentInterface $doc,
@@ -189,7 +189,7 @@ private function nodeAddChilds(
 
                 // If the array is not associative (with new nodes) error.
                 if (isset($child[0])) {
-                    throw new InvalidArgumentException(sprintf(
+                    throw new XmlEncoderException(sprintf(
                         'The node "%s" allows including arrays, but they must be arrays with other nodes. The current value is incorrect: %s',
                         $tagName,
                         json_encode($child)

src/XPathQuery.php

@@ -12,12 +12,13 @@
 
 namespace Derafu\Xml;
 
+use Derafu\Xml\Contract\XmlDocumentInterface;
+use Derafu\Xml\Exception\XmlParseException;
+use Derafu\Xml\Exception\XmlQueryException;
 use DOMDocument;
 use DOMNode;
 use DOMNodeList;
 use DOMXPath;
-use InvalidArgumentException;
-use LogicException;
 
 /**
  * Class to facilitate XML handling using XPath.
@@ -48,18 +49,18 @@ final class XPathQuery
     /**
      * Constructor that receives the XML document and prepares XPath.
      *
-     * @param string|DOMDocument $xml XML document.
+     * @param string|XmlDocumentInterface|DOMDocument $xml XML document.
      * @param array $namespaces Associative array with prefix and URI.
      */
     public function __construct(
-        string|DOMDocument $xml,
+        string|XmlDocumentInterface|DOMDocument $xml,
         array $namespaces = []
     ) {
         // Assign the DOM document instance.
-        if ($xml instanceof DOMDocument) {
+        if ($xml instanceof XmlDocumentInterface || $xml instanceof DOMDocument) {
             $this->dom = $xml;
         } else {
-            $this->dom = new DOMDocument();
+            $this->dom = new XmlDocument();
             $this->loadXml($xml);
         }
 
@@ -194,8 +195,8 @@ public function getNodes(
                 $contextNode,
                 $this->registerNodeNS
             ));
-        } catch (LogicException $e) {
-            throw new InvalidArgumentException(sprintf(
+        } catch (XmlQueryException $e) {
+            throw new XmlQueryException(sprintf(
                 'An error occurred while executing the XPath expression: %s. %s',
                 $query,
                 $e->getMessage()
@@ -213,14 +214,9 @@ public function getNodes(
      */
     private function loadXml(string $xml): static
     {
-        try {
-            $this->execute(fn () => $this->dom->loadXml($xml));
-        } catch (LogicException $e) {
-            throw new InvalidArgumentException(sprintf(
-                'The provided XML is not valid: %s',
-                $e->getMessage()
-            ));
-        }
+        // XmlDocument::loadXml() throws XmlParseException if the XML is
+        // empty or malformed, propagating it directly to the caller.
+        $this->dom->loadXml($xml);
 
         return $this;
     }
@@ -346,7 +342,7 @@ private function execute(callable $function): mixed
             libxml_use_internal_errors($use_errors);
 
             $message = $error ?: 'Ocurrió un error en XPathQuery.';
-            throw new LogicException($message);
+            throw new XmlQueryException($message);
         }
 
         libxml_clear_errors();

src/XmlDocument.php

@@ -13,7 +13,8 @@
 namespace Derafu\Xml;
 
 use Derafu\Xml\Contract\XmlDocumentInterface;
-use Derafu\Xml\Exception\XmlException;
+use Derafu\Xml\Exception\XmlParseException;
+use Derafu\Xml\Exception\XmlQueryException;
 use DOMDocument;
 use DOMElement;
 use DOMNode;
@@ -95,39 +96,11 @@ public function loadXml(string $source, int $options = 0): bool
     {
         // If there is no XML string in the source, then an exception is thrown.
         if (empty($source)) {
-            throw new XmlException(
+            throw new XmlParseException(
                 'The XML content that you want to load is empty.'
             );
         }
 
-        // Convert the XML if necessary.
-        preg_match(
-            '/<\?xml\s+version="([^"]+)"\s+encoding="([^"]+)"\?>/',
-            $source,
-            $matches
-        );
-        //$version = $matches[1] ?? $this->xmlVersion;
-        $encoding = strtoupper($matches[2] ?? $this->encoding);
-        if ($encoding === 'UTF-8' && $this->encoding === 'ISO-8859-1') {
-            $source = mb_convert_encoding($source, 'ISO-8859-1', 'UTF-8');
-            $source = str_replace(
-                ' encoding="UTF-8"?>',
-                ' encoding="ISO-8859-1"?>',
-                $source
-            );
-        }
-
-        // If the XML that will be loaded does not start with the XML tag, it
-        // is added. This is 100% necessary because if it comes in a different
-        // encoding to UTF-8 (the most normal) and does not come with this tag
-        // opening the XML, it will complain that the encoding is missing when
-        // loading.
-        if (!str_starts_with($source, '<?xml')) {
-            $source = '<?xml version="1.0" encoding="' . $encoding . '"?>'
-                . "\n" . $source
-            ;
-        }
-
         // Get the current state of libxml and change it before loading the XML
         // to get the errors in a variable if something fails.
         $useInternalErrors = libxml_use_internal_errors(true);
@@ -141,7 +114,7 @@ public function loadXml(string $source, int $options = 0): bool
         libxml_use_internal_errors($useInternalErrors);
 
         if (!$status) {
-            throw new XmlException('Error al cargar el XML.', $errors);
+            throw new XmlParseException('Error al cargar el XML.', $errors);
         }
 
         // Return the status of the XML loading.
@@ -183,7 +156,7 @@ public function C14NWithIso88591Encoding(?string $xpath = null): string
         if ($xpath) {
             $node = $this->getNodes($xpath)->item(0);
             if (!$node) {
-                throw new XmlException(sprintf(
+                throw new XmlQueryException(sprintf(
                     'No fue posible obtener el nodo con el XPath %s.',
                     $xpath
                 ));

src/XmlHelper.php

@@ -12,10 +12,10 @@
 
 namespace Derafu\Xml;
 
+use Derafu\Xml\Exception\XmlQueryException;
 use DOMDocument;
 use DOMNodeList;
 use DOMXPath;
-use InvalidArgumentException;
 
 /**
  * Class with utilities to work with XML strings.
@@ -44,7 +44,7 @@ public static function xpath(
         $result = @$xpath->query($expression);
 
         if ($result === false) {
-            throw new InvalidArgumentException(sprintf(
+            throw new XmlQueryException(sprintf(
                 'Invalid XPath expression: %s',
                 $expression
             ));

tests/fixtures/encode_and_decode.php

@@ -354,9 +354,8 @@
         // XML en UTF-8 con caracteres especiales (ej. tildes, ñ).
         'utf8_characters' => [
             'xmlContent' => '<?xml version="1.0" encoding="UTF-8"?><root><element>Árbol</element></root>',
-            'expected' => '<?xml version="1.0" encoding="ISO-8859-1"?>' . "\n" . '<root>'
-                . "\n" . '  <element>' . mb_convert_encoding('Árbol', 'ISO-8859-1', 'UTF-8')
-                . '</element>' . "\n" . '</root>' . "\n",
+            'expected' => '<?xml version="1.0" encoding="UTF-8"?>' . "\n" . '<root>'
+                . "\n" . '  <element>Árbol</element>' . "\n" . '</root>' . "\n",
             'expectedException' => null,
         ],
         // XML en ISO-8859-1 con caracteres especiales (ej. tildes, ñ).

tests/fixtures/encoding/iso88591-comprehensive.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Derafu: XML - Library for XML manipulation.
+ *
+ * Copyright (c) 2026 Esteban De La Fuente Rubio / Derafu <https://www.derafu.dev>
+ * Licensed under the MIT License.
+ * See LICENSE file for more details.
+ */
+
+/**
+ * Returns an XML string with a comprehensive set of ISO-8859-1 characters,
+ * encoded as actual ISO-8859-1 bytes (not UTF-8, not XML entities).
+ *
+ * The content is defined here as UTF-8 string literals (the natural encoding
+ * of PHP source files) and converted to ISO-8859-1 before being returned.
+ *
+ * Characters covered:
+ *   - Lowercase accented vowels : á é í ó ú à è ì ò ù
+ *   - Uppercase accented vowels : Á É Í Ó Ú À È Ì Ò Ù
+ *   - Spanish ñ/Ñ
+ *   - Umlaut vowels             : ü Ü ö Ö
+ *   - Spanish punctuation       : ¿ ¡
+ *   - Common symbols            : © ® ° ½ ¼ ¾
+ *   - A representative sentence : Fabricación de Ñoños en Güemes
+ *
+ * @return string XML content encoded in ISO-8859-1.
+ */
+
+$xml = '<?xml version="1.0" encoding="ISO-8859-1"?>' . "\n"
+    . '<documento>' . "\n"
+    . '  <vocales_min>á é í ó ú à è ì ò ù</vocales_min>' . "\n"
+    . '  <vocales_may>Á É Í Ó Ú À È Ì Ò Ù</vocales_may>' . "\n"
+    . '  <enie>ñ Ñ</enie>' . "\n"
+    . '  <dieresis>ü Ü ö Ö</dieresis>' . "\n"
+    . '  <puntuacion>¿Hola? ¡Mundo!</puntuacion>' . "\n"
+    . '  <simbolos>© ® ° ½ ¼ ¾</simbolos>' . "\n"
+    . '  <frase>Fabricación de Ñoños en Güemes</frase>' . "\n"
+    . '</documento>' . "\n"
+;
+
+return mb_convert_encoding($xml, 'ISO-8859-1', 'UTF-8');