Mistralys / application-utils

src/XMLHelper/Converter.php

<?php
/**
 * File containing the {@link XMLHelper_Converter} class.
 * 
 * @package Application Utils
 * @subpackage XMLHelper
 * @see XMLHelper_Converter
 */

namespace AppUtils;

use AppUtils\ConvertHelper\JSONConverter;
use AppUtils\ConvertHelper\JSONConverter\JSONConverterException;
use DOMElement;
use Exception;
use SimpleXMLElement;

/**
 * Simple XML converter that can transform an XML document
 * to JSON or an associative array.
 * 
 * It uses a custom JSON decorator to convert a SimpleXMLElement,
 * which solves many of the usual issues when trying to convert
 * those to JSON. It is not a catch-all, but works well with
 * most XML documents.
 * 
 * Converting an XML file to array:
 * 
 * <pre>
 * $converter = XMLHelper_Converter::fromFile('path/to/xml/file.xml');
 * $array = $converter->toArray();
 * </pre>
 * 
 * Converting an XML string to array:
 * 
 * <pre>
 * $converter = XMLHelper_Converter::fromString('<document>XML source here</document>');
 * $array = $converter->toArray();
 * </pre>
 * 
 * @package Application Utils
 * @subpackage XMLHelper
 * @author Sebastian Mordziol <s.mordziol@mistralys.eu>
 *
 */
class XMLHelper_Converter
{
    public const ERROR_FAILED_CONVERTING_TO_JSON = 37901;
    public const ERROR_CANNOT_CREATE_ELEMENT_FROM_STRING = 37902;
    public const ERROR_FAILED_CONVERTING_TO_ARRAY = 37902;
    
    protected SimpleXMLElement $xml;
    
   /**
    * @var string|NULL
    */
    protected ?string $json;
    
    protected function __construct(SimpleXMLElement $element)
    {
        $this->xml = $element;
    }

    /**
     * Factory method: creates a converter from an XML file on disk.
     *
     * @param string $path
     * @return XMLHelper_Converter
     * @throws FileHelper_Exception
     * @throws XMLHelper_Exception
     */
    public static function fromFile(string $path) : XMLHelper_Converter
    {
        return self::fromString(FileHelper::readContents($path));
    }

    /**
     * Factory method: creates a converter from an XML string.
     *
     * @param string $xmlString
     * @return XMLHelper_Converter
     * @throws XMLHelper_Exception
     */
    public static function fromString(string $xmlString) : XMLHelper_Converter
    {
        try
        {
            return self::fromElement(new SimpleXMLElement($xmlString));
        }
        catch (Exception $e)
        {
            throw new XMLHelper_Exception(
                'Cannot create new element from string.',
                '',
                self::ERROR_CANNOT_CREATE_ELEMENT_FROM_STRING,
                $e
            );
        }
    }
    
   /**
    * Factory method: creates a converter from an existing SimpleXMLElement instance.
    * 
    * @param SimpleXMLElement $element
    * @return XMLHelper_Converter
    */
    public static function fromElement(SimpleXMLElement $element) : XMLHelper_Converter
    {
        return new XMLHelper_Converter($element);
    }

   /**
    * Factory method: creates a converter from an existing SimpleXMLElement instance.
    *
    * @param DOMElement $element
    * @return XMLHelper_Converter
    */
    public static function fromDOMElement(DOMElement $element) : XMLHelper_Converter
    {
        return new XMLHelper_Converter(simplexml_import_dom($element));
    }
    
   /**
    * Converts the XML to JSON.
    * 
    * @return string
    * @throws XMLHelper_Exception
    */
    public function toJSON() : string
    {
        if (isset($this->json))
        {
            return $this->json;

The expression return $this->json could return the type null which is incompatible with the type-hinted return string. Consider adding an additional type-check to rule them out.

        }

        $decorator = new XMLHelper_Converter_Decorator($this->xml);

        try
        {
            $this->json = JSONConverter::var2json($decorator, JSON_PRETTY_PRINT);

            unset($this->xml);

            return $this->json;

The expression return $this->json returns the type null which is incompatible with the type-hinted return string.

        }
        catch (JSONConverterException $e)
        {
            throw new XMLHelper_Exception(
                'Could not convert the XML source to JSON.',
                sprintf(
                    'XML source excerpt: '.PHP_EOL.
                    '-----------------------------------------------------------'.
                    '%s'.PHP_EOL.
                    '-----------------------------------------------------------',
                    ConvertHelper::text_cut($this->xml, 300)
                ),
                self::ERROR_FAILED_CONVERTING_TO_JSON,
                $e
            );
        }
    }

    /**
     * Converts the XML to an associative array.
     * @return array<mixed>
     *
     * @throws XMLHelper_Exception
     */
    public function toArray() : array 
    {
        try
        {
            return JSONConverter::json2array($this->toJSON());
        }
        catch (JSONConverterException $e)
        {
            throw new XMLHelper_Exception(
                'Could not convert the JSON string to an array.',
                '',
                self::ERROR_FAILED_CONVERTING_TO_ARRAY,
                $e
            );
        }
    }
}