Derafu\Lib\Core\Package\Prime\Component\Xml\Entity\Xml

Complexity

Total Complexity

18

Size/Duplication

Total Lines	231
Duplicated Lines	0 %

Test Coverage

Coverage

89.33%

Importance

Changes

0

10 Methods

Rating	Name	Duplication	Size	Complexity
A	__construct()	0	8	1
A	C14NWithIsoEncoding()	0	27	3
A	getXml()	0	10	1
A	C14NWithIsoEncodingFlattened()	0	10	1
A	getName()	0	3	1
A	getSignatureNodeXml()	0	7	1
A	saveXml()	0	5	1
A	loadXml()	0	45	4
A	getNamespace()	0	5	2
A	getSchema()	0	11	3

<?php

declare(strict_types=1);

/**
 * Derafu: Biblioteca PHP (Núcleo).
 * Copyright (C) Derafu <https://www.derafu.org>
 *
 * Este programa es software libre: usted puede redistribuirlo y/o modificarlo
 * bajo los términos de la Licencia Pública General Affero de GNU publicada por
 * la Fundación para el Software Libre, ya sea la versión 3 de la Licencia, o
 * (a su elección) cualquier versión posterior de la misma.
 *
 * Este programa se distribuye con la esperanza de que sea útil, pero SIN
 * GARANTÍA ALGUNA; ni siquiera la garantía implícita MERCANTIL o de APTITUD
 * PARA UN PROPÓSITO DETERMINADO. Consulte los detalles de la Licencia Pública
 * General Affero de GNU para obtener una información más detallada.
 *
 * Debería haber recibido una copia de la Licencia Pública General Affero de GNU
 * junto a este programa.
 *
 * En caso contrario, consulte <http://www.gnu.org/licenses/agpl.html>.
 */

namespace Derafu\Lib\Core\Package\Prime\Component\Xml\Entity;

use Derafu\Lib\Core\Helper\Str;
use Derafu\Lib\Core\Helper\Xml as XmlUtil;
use Derafu\Lib\Core\Package\Prime\Component\Xml\Exception\XmlException;
use DomDocument;
use DOMNode;

/**
 * Clase que representa un documento XML.
 */
class Xml extends DomDocument
{
    /**
     * Constructor del documento XML.
     *
     * @param string $version Versión del documento XML.
     * @param string $encoding Codificación del documento XML.
     */
    public function __construct(
        string $version = '1.0',
        string $encoding = 'ISO-8859-1'
    ) {
        parent::__construct($version, $encoding);

        $this->formatOutput = true;
        $this->preserveWhiteSpace = true;
    }

    /**
     * Entrega el nombre del tag raíz del XML.
     *
     * @return string Nombre del tag raíz.
     */
    public function getName(): string
    {
        return $this->documentElement->tagName;
    }

    /**
     * Obtiene el espacio de nombres (namespace) del elemento raíz del
     * documento XML.
     *
     * @return string|null Espacio de nombres del documento XML o `null` si no
     * está presente.
     */
    public function getNamespace(): ?string
    {
        $namespace = $this->documentElement->getAttribute('xmlns');

        return $namespace !== '' ? $namespace : null;
    }

    /**
     * Entrega el nombre del archivo del schema del XML.
     *
     * @return string|null Nombre del schema o `null` si no se encontró.
     */
    public function getSchema(): ?string
    {
        $schemaLocation = $this->documentElement->getAttribute(
            'xsi:schemaLocation'
        );

        if (!$schemaLocation || !str_contains($schemaLocation, ' ')) {
            return null;
        }

        return explode(' ', $schemaLocation)[1];
    }

    /**
     * Carga un string XML en la instancia del documento XML.
     *
     * @param string $source String con el documento XML a cargar.
     * @param int $options Opciones para la carga del XML.
     * @return bool `true` si el XML se cargó correctamente.
     * @throws XmlException Si no es posible cargar el XML.
     */
    public function loadXml(string $source, int $options = 0): bool
    {
        // Si no hay un string XML en el origen entonces se lanza excepción.
        if (empty($source)) {
            throw new XmlException(
                'El contenido del XML que se desea cargar está vacío.'
            );
        }

        // Convertir el XML si es necesario.
        preg_match(
            '/<\?xml\s+version="([^"]+)"\s+encoding="([^"]+)"\?>/',
            $source,
            $matches
        );
        //$version = $matches[1] ?? $this->xmlVersion;
        $encoding = strtoupper($matches[2] ?? $this->encoding);
        if ($encoding === 'UTF-8') {
            $source = Str::utf8decode($source);
            $source = str_replace(
                ' encoding="UTF-8"?>',
                ' encoding="ISO-8859-1"?>',
                $source
            );
        }

        // Obtener estado actual de libxml y cambiarlo antes de cargar el XML
        // para obtener los errores en una variable si falla algo.
        $useInternalErrors = libxml_use_internal_errors(true);

        // Cargar el XML.
        $status = parent::loadXml($source, $options);

        // Obtener errores, limpiarlos y restaurar estado de errores de libxml.
        $errors = libxml_get_errors();
        libxml_clear_errors();
        libxml_use_internal_errors($useInternalErrors);

        if (!$status) {
            throw new XmlException('Error al cargar el XML.', $errors);
        }

        // Retornar estado de la carga del XML.
        // Sólo retornará `true`, pues si falla lanza excepción.
        return true;
    }

    /**
     * Genera el documento XML como string.
     *
     * Wrapper de parent::saveXml() para poder corregir XML entities.
     *
     * Incluye encabezado del XML con versión y codificación.
     *
     * @param DOMNode|null $node Nodo a serializar.
     * @param int $options Opciones de serialización.
     * @return string XML serializado y corregido.
     */
    public function saveXml(?DOMNode $node = null, int $options = 0): string
    {
        $xml = parent::saveXml($node, $options);

        return XmlUtil::fixEntities($xml);
    }

    /**
     * Genera el documento XML como string.
     *
     * Wrapper de saveXml() para generar un string sin el encabezado del XML y
     * sin salto de línea inicial o final.
     *
     * @return string XML serializado y corregido.
     */
    public function getXml(): string
    {
        $xml = $this->saveXml();
        $xml = preg_replace(
            '/<\?xml\s+version="1\.0"\s+encoding="[^"]+"\s*\?>/i',
            '',
            $xml
        );

        return trim($xml);
    }

    /**
     * Entrega el string XML canonicalizado y con la codificación que
     * corresponde (ISO-8859-1).
     *
     * Esto básicamente usa C14N(), sin embargo, C14N() siempre entrega el XML
     * en codificación UTF-8. Por lo que este método permite obtenerlo con C14N
     * pero con la codificación correcta de ISO-8859-1. Además se corrigen las
     * XML entities.
     *
     * @param string|null $xpath XPath para consulta al XML y extraer solo una
     * parte, desde un tag/nodo específico.
     * @return string String XML canonicalizado.
     * @throws XmlException En caso de ser pasado un XPath y no encontrarlo.
     */
    public function C14NWithIsoEncoding(?string $xpath = null): string
    {
        // Si se proporciona XPath, filtrar los nodos.
        if ($xpath) {
            $node = XmlUtil::xpath($this, $xpath)->item(0);
            if (!$node) {
                throw new XmlException(sprintf(
                    'No fue posible obtener el nodo con el XPath %s.',
                    $xpath
                ));
            }
            $xml = $node->C14N();
        }
        // Usar C14N() para todo el documento si no se especifica XPath.
        else {
            $xml = $this->C14N();
        }

        // Corregir XML entities.
        $xml = XmlUtil::fixEntities($xml);

        // Convertir el XML aplanado de UTF-8 a ISO-8859-1.
        // Requerido porque C14N() siempre entrega los datos en UTF-8.
        $xml = Str::utf8decode($xml);

        // Entregar el XML canonicalizado.
        return $xml;
    }

    /**
     * Entrega el string XML canonicalizado, con la codificación que
     * corresponde (ISO-8859-1) y aplanado.
     *
     * Es un wrapper de C14NWithIsoEncoding() que aplana el XML resultante.
     *
     * @param string|null $xpath XPath para consulta al XML y extraer solo una
     * parte, desde un tag/nodo específico.
     * @return string String XML canonicalizado y aplanado.
     * @throws XmlException En caso de ser pasado un XPath y no encontrarlo.
     */
    public function C14NWithIsoEncodingFlattened(?string $xpath = null): string
    {
        // Obtener XML canonicalizado y codificado en ISO8859-1.
        $xml = $this->C14NWithIsoEncoding($xpath);

        // Eliminar los espacios entre tags.
        $xml = preg_replace("/>\s+</", '><', $xml);

        // Entregar el XML canonicalizado y aplanado.
        return $xml;
    }

    /**
     * Obtiene el string del nodo de la firma electrónica del XML.
     *
     * @return string|null String XML de la firma si existe.
     */
    public function getSignatureNodeXml(): ?string
    {
        $tag = $this->documentElement->tagName;
        $xpath = '/*[local-name()="' . $tag . '"]/*[local-name()="Signature"]';
        $signatureElement = XmlUtil::xpath($this, $xpath)->item(0);

        return $signatureElement?->C14N();
    }
}