README

A comprehensive PHP library for XML manipulation, providing robust tools for encoding, decoding, validating, and querying XML documents.

Features

Conversion: Transform between XML and PHP arrays in both directions.
Validation: Validate XML documents against XSD schemas.
Querying: Powerful XPath querying with parameter support.
Canonicalization: Support for C14N and ISO-8859-1 encoding.
Encoding: Proper handling of character encoding between UTF-8 and ISO-8859-1.
Special Characters: Automatic handling of XML special characters and entities.

Installation

composer require derafu/xml

Basic Usage

Creating XML from an Array

use Derafu\Xml\Service\XmlEncoder;

$encoder = new XmlEncoder();

// Create an array to convert to XML.
$data = [
    'root' => [
        'element1' => 'value1',
        'element2' => 'value2',
        'element3' => [
            '@attributes' => [
                'attr1' => 'attrValue',
            ],
            '@value' => 'value3',
        ],
        'repeatedElement' => ['value4', 'value5', 'value6'],
    ],
];

// Convert the array to XML.
$xmlDocument = $encoder->encode($data);

// Save as XML string.
$xmlString = $xmlDocument->saveXml();

// Get the XML without the XML declaration.
$xmlContent = $xmlDocument->getXml();

// Get a canonicalized version of the XML.
$c14nXml = $xmlDocument->C14N();

// Get a canonicalized version with ISO-8859-1 encoding.
$isoXml = $xmlDocument->C14NWithIso88591Encoding();

Converting XML to an Array

use Derafu\Xml\Service\XmlDecoder;
use Derafu\Xml\XmlDocument;

$decoder = new XmlDecoder();

// Load an existing XML string.
$xmlContent = '<?xml version="1.0" encoding="UTF-8"?><root><element>value</element></root>';
$document = new XmlDocument();
$document->loadXml($xmlContent);

// Convert to an array.
$array = $decoder->decode($document);

// Now $array contains ['root' => ['element' => 'value']]

Working with XPath

use Derafu\Xml\XPathQuery;

$xmlContent = '<?xml version="1.0"?><root><item id="1">First</item><item id="2">Second</item></root>';

// Create XPath query instance.
$query = new XPathQuery($xmlContent);

// Get a specific value.
$value = $query->getValue('/root/item[@id="2"]'); // "Second"

// Get multiple values.
$values = $query->getValues('/root/item'); // ["First", "Second"]

// Get structured array.
$array = $query->get('/root');
// Result: ['item' => ['First', 'Second']]

XML Validation

use Derafu\Xml\Exception\XmlException;
use Derafu\Xml\Service\XmlValidator;

$validator = new XmlValidator();

// Validate an XML document against a schema.
try {
    $validator->validate($xmlDocument, '/path/to/schema.xsd');
    echo "XML is valid!";
} catch (XmlException $e) {
    echo "Validation failed: " . $e->getMessage();
    $errors = $e->getErrors(); // Get detailed error information.
}

Advanced Usage

Working with Namespaces

// Create XPath query with namespace support.
$namespaces = ['ns' => 'http://example.com/namespace'];
$query = new XPathQuery($xmlContent, $namespaces);

// Query with namespace.
$result = $query->get('//ns:Element');

Array Structure for XML Creation

When creating XML from arrays, the structure follows these conventions:

Simple key-value pairs become element nodes.
Use @attributes for node attributes.
Use @value for node text content when attributes are present.
Arrays of values create repeated nodes with the same name.

Example:

$data = [
    'root' => [
        'element' => [
            '@attributes' => ['id' => '123'],
            '@value' => 'content',
        ],
        'items' => [
            'item' => ['value1', 'value2', 'value3'],
        ],
    ],
];

Produces:

<root>
  <element id="123">content</element>
  <items>
    <item>value1</item>
    <item>value2</item>
    <item>value3</item>
  </items>
</root>

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This package is open-sourced software licensed under the MIT license.

derafu / xml

Maintainers

Details