README

UXML is an extremely simple PHP library for manipulating XML documents with ease while keeping overhead to a bare minimum.

It consist of just a single class which uses the PHP built-in DOMElement and DOMDocument classes under the hood.

Installation

Using Composer

composer require josemmo/uxml

Without Composer

Download source files from the GitHub repository:

git clone https://github.com/josemmo/uxml.git

Use the UXML class in your app:

use UXML\UXML;
require_once __DIR__ . "/uxml/src/UXML.php";

FAQ

Why use this instead of sabre/xml or FluidXML?
Both those options are great and if they fit your project you should definetely use them! However, in my case I needed something more lightweight to put on top of LibXML's DOM to provide an alternative syntax.

Is UXML compatible with DOMElement?
Yes, indeed! You can get the original DOMElement instance from an UXML object and vice versa.

I want UXML to do "X". Can you implement it?
My main goal with this project is not to implement all possible behaviors in the XML specification, you can use the DOM or SimpleXML libraries for that.

Usage

Create a new document

UXML does not distinguish between XML documents (DOMDocument) and elements (DOMElement). Instead, you can create a new document like so:

$xml = \UXML\UXML::newInstance('RootTagName');

You can also wrap an already existing DOMElement:

$domElement = new DOMElement('TagName');
$xml = \UXML\UXML::fromElement($domElement);

Load an XML document from source

By loading an XML string, UXML will return the root element of the document tree:

$source = <<<XML
<fruits>
    <fruit>Banana</fruit>
    <fruit>Apple</fruit>
    <fruit>Tomato</fruit>
</fruits>
XML;
$xml = \UXML\UXML::fromString($source);

Add elements to a node

When adding an element, UXML will return a reference to the newly created element:

$xml = \UXML\UXML::newInstance('Parent');
$child = $xml->add('Child');
echo $child; // <Child />
echo $xml;   // <Parent><Child /></Parent>

You can also define a value:

$child = $xml->add('Child', 'Hello World!');
echo $child; // <Child>Hello World!</Child>

And even attributes or namespaces:

$feed = \UXML\UXML::newInstance('feed', null, [
    'xmlns' => 'http://www.w3.org/2005/Atom'
]);
echo $feed; // <feed xmlns="http://www.w3.org/2005/Atom" />

$link = $feed->add('link', 'Wow!', [
    'href' => 'https://www.example.com'
]);
echo $link; // <link href="https://www.example.com">Wow!</link>

Element chaining

Because with every element insertion a reference to the new element is returned, you can chain multiple of these calls to create a tree:

$xml = \UXML\UXML::newInstance('people');
$xml->add('person')->add('name', 'Jane Doe');
echo $xml; // <people>
           //     <person>
           //         <name>Jane Doe</name>
           //     </person>
           // </people>

Export XML source

Besides casting UXML objects to a string, there is a method for exporting the XML source of an element and its children:

$xml->asXML();

By default, exported strings include an XML declaration (except when casting UXML instances to a string).

Find XML elements

UXML allows you to use XPath 1.0 queries to get a particular element from a document:

$xml = \UXML\UXML::newInstance('person');
$xml->add('name', 'Jane');
$xml->add('surname', 'Doe');
$xml->add('color', 'green', ['hex' => '#0f0']);

echo $xml->get('*[@hex]'); // <color hex="#0f0">green</color>
var_dump($xml->get('birthday')); // NULL

Or even multiple elements:

$xml = \UXML\UXML::fromString('<a><b>1</b><b>2</b><b>3</b></a>');
foreach ($xml->getAll('b') as $elem) {
    echo "Element says: " . $elem->asText() . "\n";
}

Note all XPath queries are relative to current element:

$source = <<<XML
<movie>
    <name>Inception</name>
    <year>2010</year>
    <director>
        <name>Christopher</name>
        <surname>Nolan</surname>
        <year>1970</year>
    </director>
</movie>
XML;
$xml = \UXML\UXML::fromString($source);

echo $xml->get('director/year'); // <year>1970</year>
echo $xml->get('director')->get('year'); // <year>1970</year>
echo $xml->get('year'); // <year>2010</year>
echo $xml->get('director')->get('//year'); // <year>2010</year>

Remove XML elements

Elements can be removed from the XML tree by calling the remove() method on them. After an element is removed, it becomes unusable:

$source = <<<XML
<project>
    <public>
        <name>Alpha</name>
    </public>
    <confidential>
        <budget>1,000,000 USD</budget>
    </confidential>
</project>
XML;
$xml = \UXML\UXML::fromString($source);
$xml->get('confidential')->remove();
echo $xml; // <project><public><name>Alpha</name></public></project>

Namespaces

Namespaces are assigned in the same way as other attributes:

$xml->add('TagName', null, [
    'xmlns' => 'https://example.com',
    'xmlns:abc' => 'urn:abc',
    'attribute' => 'value'
])->add('abc:Child', 'Name');
echo $xml; // <TagName xmlns="https://example.com"
           //  xmlns:abc="urn:abc"
           //  attribute="value">
           //     <abc:Child>Name</abc:Child>
           // </TagName>

However, when querying elements, the prefix defined in the document may not be the one you are expecting:

$xml = \UXML\UXML::fromString('<a xmlns:ns="urn:abc"><ns:b /></a>');
echo $xml->get('ns:b'); // <ns:b />
echo $xml->get('abc:b'); // Is NULL as the prefix does not exist

To fix this, you can make use of clark notation inside the XPath query:

echo $xml->get('{urn:abc}b'); // <ns:b />

Advanced XML manipulation

For any other document manipulation outside the scope of this library, you can always interact with the DOMElement instance:

$xml = \UXML\UXML::newInstance('Test');
$xml->element(); // Returns a [DOMElement] object

josemmo / uxml

Maintainers

Details