xml-navigator

Public API reference

This file documents every public method of the current runtime API. Constructors and jsonSerialize() are intentionally omitted from the example sections.

Index

• FastXmlToArray
• XmlConverter
• FastXmlParser
• XmlParser
• XmlElement
• XmlAttribute

Shared pretty-print showcase

All prettyPrint examples use the same XML input so the output rules are easy to compare at a glance.

Input:

<root>
  <item>value-only</item>
  <item code="A" />
  <item code="B">value-and-attributes</item>
  <item />
</root>

This single input shows every important output form:

• one element with only a text value;
• one element with only attributes;
• one element with both value and attributes;
• one empty element with neither value nor attributes;
• repeated elements with the same name, collected into an indexed list.

FastXmlToArray

convert()

Convert a full XML document into the stable hierarchy format.

use SbWereWolf\XmlNavigator\Conversion\FastXmlToArray;

$xml = <<<'XML'
<catalog region="eu">
  <offer id="1001">
    <name>Keyboard</name>
    <price currency="USD">49.90</price>
  </offer>
</catalog>
XML;

$result = FastXmlToArray::convert($xml);

Result:

[
    'n' => 'catalog',
    'a' => [
        'region' => 'eu',
    ],
    's' => [
        [
            'n' => 'offer',
            'a' => [
                'id' => '1001',
            ],
            's' => [
                [
                    'n' => 'name',
                    'v' => 'Keyboard',
                ],
                [
                    'n' => 'price',
                    'v' => '49.90',
                    'a' => [
                        'currency' => 'USD',
                    ],
                ],
            ],
        ],
    ],
]

prettyPrint()

Convert a full XML document into the readable pretty-print format.

use SbWereWolf\XmlNavigator\Conversion\FastXmlToArray;

$xml = <<<'XML'
<root>
  <item>value-only</item>
  <item code="A" />
  <item code="B">value-and-attributes</item>
  <item />
</root>
XML;

$result = FastXmlToArray::prettyPrint($xml);

Result:

[
    'root' => [
        'item' => [
            'value-only',
            [
                '@attributes' => [
                    'code' => 'A',
                ],
            ],
            [
                '@value' => 'value-and-attributes',
                '@attributes' => [
                    'code' => 'B',
                ],
            ],
            [],
        ],
    ],
]

XmlConverter

XmlConverter keeps the same conversion logic, but lets you rename the array keys once and reuse that notation.

toHierarchyOfElements()

use SbWereWolf\XmlNavigator\Conversion\XmlConverter;

$converter = new XmlConverter(
    val: 'value',
    attr: 'attributes',
    name: 'name',
    seq: 'children',
);

$result = $converter->toHierarchyOfElements(
    '<price currency="USD">129.90</price>'
);

Result:

[
    'name' => 'price',
    'value' => '129.90',
    'attributes' => [
        'currency' => 'USD',
    ],
]

toPrettyPrint()

use SbWereWolf\XmlNavigator\Conversion\XmlConverter;

$converter = new XmlConverter(
    val: 'value',
    attr: 'attributes',
);

$result = $converter->toPrettyPrint(
    <<<'XML'
<root>
  <item>value-only</item>
  <item code="A" />
  <item code="B">value-and-attributes</item>
  <item />
</root>
XML
);

Result:

[
    'root' => [
        'item' => [
            'value-only',
            [
                'attributes' => [
                    'code' => 'A',
                ],
            ],
            [
                'value' => 'value-and-attributes',
                'attributes' => [
                    'code' => 'B',
                ],
            ],
            [],
        ],
    ],
]

FastXmlParser

FastXmlParser is the hierarchy-first streaming API for large files.

extractHierarchy()

use SbWereWolf\XmlNavigator\Parsing\FastXmlParser;

$reader = XMLReader::XML(<<<'XML'
<catalog>
  <offer id="1001"><name>Keyboard</name></offer>
  <service id="s-1"><name>Warranty</name></service>
  <offer id="1002"><name>Mouse</name></offer>
</catalog>
XML);

$offers = iterator_to_array(
    FastXmlParser::extractHierarchy(
        $reader,
        static fn (XMLReader $cursor): bool => $cursor->name === 'offer'
    ),
    false
);

Result:

[
    [
        'n' => 'offer',
        'a' => [
            'id' => '1001',
        ],
        's' => [
            [
                'n' => 'name',
                'v' => 'Keyboard',
            ],
        ],
    ],
    [
        'n' => 'offer',
        'a' => [
            'id' => '1002',
        ],
        's' => [
            [
                'n' => 'name',
                'v' => 'Mouse',
            ],
        ],
    ],
]

extractPrettyPrint()

use SbWereWolf\XmlNavigator\Parsing\FastXmlParser;

$reader = XMLReader::XML(<<<'XML'
<root>
  <item>value-only</item>
  <item code="A" />
  <item code="B">value-and-attributes</item>
  <item />
</root>
XML);

$items = iterator_to_array(
    FastXmlParser::extractPrettyPrint(
        $reader,
        static fn (XMLReader $cursor): bool => $cursor->name === 'item'
    ),
    false
);

Result:

[
    ['item' => 'value-only'],
    [
        'item' => [
            '@attributes' => [
                'code' => 'A',
            ],
        ],
    ],
    [
        'item' => [
            '@value' => 'value-and-attributes',
            '@attributes' => [
                'code' => 'B',
            ],
        ],
    ],
    ['item' => []],
]

extractHierarchy() with custom notation

Custom key names can be applied directly in FastXmlParser, without switching to XmlParser.

use SbWereWolf\XmlNavigator\Parsing\FastXmlParser;

$reader = XMLReader::XML(<<<'XML'
<catalog>
  <offer id="1001"><name>Keyboard</name></offer>
</catalog>
XML);

$offers = iterator_to_array(
    FastXmlParser::extractHierarchy(
        $reader,
        static fn (XMLReader $cursor): bool => $cursor->name === 'offer',
        'value',
        'attributes',
        'name',
        'children',
    ),
    false
);

Result:

[
    [
        'name' => 'offer',
        'attributes' => [
            'id' => '1001',
        ],
        'children' => [
            [
                'name' => 'name',
                'value' => 'Keyboard',
            ],
        ],
    ],
]

XmlParser

XmlParser wraps FastXmlParser in an object that stores the chosen notation.

extractHierarchy()

use SbWereWolf\XmlNavigator\Parsing\XmlParser;

$reader = XMLReader::XML(<<<'XML'
<dataset>
  <row id="1"><value>alpha</value></row>
  <row id="2"><value>beta</value></row>
</dataset>
XML);

$parser = new XmlParser(
    val: 'value',
    attr: 'attributes',
    name: 'name',
    seq: 'children',
);

$rows = iterator_to_array(
    $parser->extractHierarchy(
        $reader,
        static fn (XMLReader $cursor): bool => $cursor->name === 'row'
    ),
    false
);

Result:

[
    [
        'name' => 'row',
        'attributes' => [
            'id' => '1',
        ],
        'children' => [
            [
                'name' => 'value',
                'value' => 'alpha',
            ],
        ],
    ],
    [
        'name' => 'row',
        'attributes' => [
            'id' => '2',
        ],
        'children' => [
            [
                'name' => 'value',
                'value' => 'beta',
            ],
        ],
    ],
]

extractPrettyPrint()

use SbWereWolf\XmlNavigator\Parsing\XmlParser;

$reader = XMLReader::XML(<<<'XML'
<root>
  <item>value-only</item>
  <item code="A" />
  <item code="B">value-and-attributes</item>
  <item />
</root>
XML);

$parser = new XmlParser(
    val: 'value',
    attr: 'attributes',
);

$items = iterator_to_array(
    $parser->extractPrettyPrint(
        $reader,
        static fn (XMLReader $cursor): bool => $cursor->name === 'item'
    ),
    false
);

Result:

[
    ['item' => 'value-only'],
    [
        'item' => [
            'attributes' => [
                'code' => 'A',
            ],
        ],
    ],
    [
        'item' => [
            'value' => 'value-and-attributes',
            'attributes' => [
                'code' => 'B',
            ],
        ],
    ],
    ['item' => []],
]

XmlElement

XmlElement is the navigation wrapper for hierarchy arrays. The examples below assume this setup:

use SbWereWolf\XmlNavigator\Conversion\FastXmlToArray;
use SbWereWolf\XmlNavigator\Navigation\XmlElement;

$xml = <<<'XML'
<catalog region="eu">
  <offer id="1001" available="true">
    <name>Keyboard</name>
    <tag>office</tag>
    <tag>usb</tag>
  </offer>
</catalog>
XML;

$root = new XmlElement(FastXmlToArray::convert($xml));
$offer = $root->pull('offer')->current();

name()

$root->name();

Result:

'catalog'

hasValue()

$offer->hasValue();

Result:

false

value()

$offer->pull('name')->current()->value();

Result:

'Keyboard'

hasAttribute()

$offer->hasAttribute('id');

Result:

true

attributes()

array_map(
    static fn ($attribute): array => [
        $attribute->name(),
        $attribute->value(),
    ],
    $offer->attributes()
);

Result:

[
    ['id', '1001'],
    ['available', 'true'],
]

get()

$offer->get('id');

Result:

'1001'

hasElement()

$offer->hasElement('tag');

Result:

true

elements()

array_map(
    static fn (XmlElement $tag): string => $tag->value(),
    $offer->elements('tag')
);

Result:

[
    'office',
    'usb',
]

pull()

$root->pull('offer')->current()->get('id');

Result:

'1001'

serialize()

$offer->serialize();

Result:

[
    'n' => 'offer',
    'a' => [
        'id' => '1001',
        'available' => 'true',
    ],
    's' => [
        [
            'n' => 'name',
            'v' => 'Keyboard',
        ],
        [
            'n' => 'tag',
            'v' => 'office',
        ],
        [
            'n' => 'tag',
            'v' => 'usb',
        ],
    ],
]

XmlAttribute

These examples assume:

$attribute = $offer->attributes()[0];

name()

$attribute->name();

Result:

'id'

value()

$attribute->value();

Result:

'1001'