DomToArray

This package provides an easy way to convert DOMDocument to PHP array.

DomToArray supports attributes, cdata and array like elements.

Main usage is to convert any XML API response to array. DomToArray consumes good old PHP DOMDocument object. XML API responses are strings which could be flawlessly loaded to DOMDocument with vaclavvanik/dom-loader.

Install

You can install this package via composer.

composer require vaclavvanik/dom-to-array

Usage

Simply pass DOMDocument

<?php

declare(strict_types=1);

use DOMDocument;
use VaclavVanik\DomToArray\DomToArray;

$doc = new DOMDocument();
$doc->loadXML('<root/>');

$result = DomToArray::toArray($doc);
// $result = ['root' => ''];

XML API responses

DomToArray is meant mainly for turning XML responses from various APIs into a plain array to work with. A typical setup drops the attributes and the response wrapper element:

<?php

declare(strict_types=1);

use VaclavVanik\DomLoader\DomLoader;
use VaclavVanik\DomToArray\DomOptions;
use VaclavVanik\DomToArray\DomToArray;

// vaclavvanik/dom-loader turns a response string into a DOMDocument or a typed exception
$doc = DomLoader::loadString($apiResponseBody);

$domOptions = DomOptions::fromArray([
    DomOptions::SKIP_ATTRIBUTES => true,
    DomOptions::OMIT_ROOT_ELEMENT => true,
]);

$result = DomToArray::toArrayWithOptions($doc, $domOptions);

A plain new DOMDocument() with loadXML() works just as well; DomLoader only adds proper error handling.

Array elements

Multiple elements with same name will create multidimensional array.

<root>
    <name>guy collection</name>
    <good_guy>
        <name>Luke Skywalker</name>
        <weapon>Lightsaber</weapon>
    </good_guy>
    <good_guy>
        <name>Gandalf</name>
        <weapon>Staff</weapon>
    </good_guy>
    <bad_guy>
        <name>Saruman</name>
        <weapon>Staff</weapon>
    </bad_guy>
    <bad_guy>
        <name>Sauron</name>
        <weapon>Ring</weapon>
    </bad_guy>
</root>

This will result in:

$result = [
    'root' => [
        'name' => 'guy collection',
        'good_guy' => [
            [
                'name' => 'Luke Skywalker',
                'weapon' => 'Lightsaber',
            ],
            [
                'name' => 'Gandalf',
                'weapon' => 'Staff',
            ],
        ],
        'bad_guy' => [
            [
                'name' => 'Saruman',
                'weapon' => 'Staff',
            ],
            [
                'name' => 'Sauron',
                'weapon' => 'Ring',
            ],
        ],
    ],
];

Attributes

Element attributes create key => value like element_name@attribute_name => attribute_value

<root attr="val">
    <single type="any"/>
    <collection type="any1"/>
    <collection type="any2"/>
    <author lang="English">Tolkien</author>
    <guy lang="Black Speech">
        <name weapon="Ring">Sauron</name>
        <weapon>Ring</weapon>
    </guy>
    <guy lang="Elvish">
        <name weapon="Staff">Gandalf</name>
        <weapon>Staff</weapon>
    </guy>
    <bad_guy lang="Unknown">
        <name weapon="Staff">Saruman</name>
        <name weapon="Ring">Sauron</name>
    </bad_guy>
</root>

This will result in:

$result = [
    'root' => [
        'single' => '',
        'single@type' => 'any',
        'collection' => [
            ['collection@type' => 'any1'],
            ['collection@type' => 'any2'],
        ],
        'author' => 'Tolkien',
        'author@lang' => 'English',
        'guy' => [
            [
                'name' => 'Sauron',
                'name@weapon' => 'Ring',
                'weapon' => 'Ring',
                'guy@lang' => 'Black Speech',
            ],
            [
                'name' => 'Gandalf',
                'name@weapon' => 'Staff',
                'weapon' => 'Staff',
                'guy@lang' => 'Elvish',
            ],
        ],
        'bad_guy' => [
            [
                'name' => 'Saruman',
                'name@weapon' => 'Staff',
            ],
            [
                'name' => 'Sauron',
                'name@weapon' => 'Ring',
            ],
        ],
        'bad_guy@lang' => 'Unknown',
    ],
    'root@attr' => 'val',
];

Cdata

Cdata are convert same as element text content.

<root>
    <good_guy>
        <name><![CDATA[<h1>Gandalf</h1>]]></name>
        <weapon>Staff</weapon>
    </good_guy>
</root>

This will result in:

$result = [
    'root' => [
        'good_guy' => [
            'name' => '<h1>Gandalf</h1>',
            'weapon' => 'Staff',
        ],
    ],
];

Comments and processing instructions

Comments and processing instructions are skipped. Text they split is joined.

<root>Gandalf <!-- comment --><?target data?>the Grey</root>

$result = [
    'root' => 'Gandalf the Grey',
];

DomOptions

Options are passed to DomToArray::toArrayWithOptions().

<?php

declare(strict_types=1);

use DOMDocument;
use VaclavVanik\DomToArray\DomOptions;
use VaclavVanik\DomToArray\DomToArray;

$domOptions = DomOptions::fromArray([DomOptions::SKIP_ATTRIBUTES => true]);
$result = DomToArray::toArrayWithOptions($doc, $domOptions);

DomOptions::SKIP_ATTRIBUTES

Sometimes it is useful to work only with elements (attributes are not needed).

<root attr="val">
    <single type="any"/>
    <collection type="any1"/>
    <collection type="any2"/>
    <author lang="English">Tolkien</author>
    <guy lang="Black Speech">
        <name weapon="Ring">Sauron</name>
        <weapon>Ring</weapon>
    </guy>
    <guy lang="Elvish">
        <name weapon="Staff">Gandalf</name>
        <weapon>Staff</weapon>
    </guy>
    <bad_guy lang="Unknown">
        <name weapon="Staff">Saruman</name>
        <name weapon="Ring">Sauron</name>
    </bad_guy>
</root>

This will result in:

$result = [
    'root' => [
        'single' => '',
        'collection' => ['', ''],
        'author' => 'Tolkien',
        'guy' => [
            [
                'name' => 'Sauron',
                'weapon' => 'Ring',
            ],
            [
                'name' => 'Gandalf',
                'weapon' => 'Staff',
            ],
        ],
        'bad_guy' => [
            'name' => ['Saruman', 'Sauron'],
        ],
    ],
];

DomOptions::KEEP_MIXED_CONTENT

By default an element that holds both text and child elements is converted to its text only and the child elements are dropped.

<root>Gandalf the <colour>Grey</colour></root>

$result = [
    'root' => 'Gandalf the ',
];

With DomOptions::KEEP_MIXED_CONTENT the text is kept under the @value key next to the child elements.

$domOptions = DomOptions::fromArray([DomOptions::KEEP_MIXED_CONTENT => true]);
$result = DomToArray::toArrayWithOptions($doc, $domOptions);

$result = [
    'root' => [
        '@value' => 'Gandalf the ',
        'colour' => 'Grey',
    ],
];

Text is concatenated as-is (whitespace included) and its position relative to the child elements is not preserved.

DomOptions::OMIT_ROOT_ELEMENT

By default the result is wrapped in the name of the root element.

<root lang="Elvish">
    <name>Gandalf</name>
    <weapon>Staff</weapon>
</root>

$result = [
    'root' => [
        'name' => 'Gandalf',
        'weapon' => 'Staff',
    ],
    'root@lang' => 'Elvish',
];

With DomOptions::OMIT_ROOT_ELEMENT the wrapper is removed and the children are returned directly.

$domOptions = DomOptions::fromArray([DomOptions::OMIT_ROOT_ELEMENT => true]);
$result = DomToArray::toArrayWithOptions($doc, $domOptions);

$result = [
    'name' => 'Gandalf',
    'weapon' => 'Staff',
    'root@lang' => 'Elvish',
];

Root element attributes keep their root@attribute keys (and are still removed by DomOptions::SKIP_ATTRIBUTES). A root element with only text content is returned as ['@value' => '...'], an empty root element as [].

DomOptions::USE_ATTRIBUTE_NODE_NAME

By default attributes are keyed by their local name, so two attributes that only differ by namespace prefix collide.

<root xmlns:x="urn:x" x:type="qualified" type="plain"/>

$result = [
    'root' => '',
    'root@type' => 'plain',
];

With DomOptions::USE_ATTRIBUTE_NODE_NAME the full attribute node name (including the namespace prefix) is used.

$domOptions = DomOptions::fromArray([DomOptions::USE_ATTRIBUTE_NODE_NAME => true]);
$result = DomToArray::toArrayWithOptions($doc, $domOptions);

$result = [
    'root' => '',
    'root@x:type' => 'qualified',
    'root@type' => 'plain',
];

Run check - coding standards and php-unit

Install dependencies:

make install

Run check:

make check

Changelog

Please see CHANGELOG for more information what has changed recently.

License

The MIT License (MIT). Please see License File for more information.