array2xml is a simple library for converting arrays to XML
There are several libraries for converting arrays to XML, but they all require special syntax for annotating schema details for things like what to send array items as, attributes, and namespaces.
I was looking for a solution that would allow consumers of other libraries to provide an array without needing to know those xml schema details.
This library separates the array data from schema data so it is ideal for use in libraries where schema details are
needed but you don't want to put that on users of your library. When instantiating the fillup\A2X class
you pass the data array as the first parameter and optionally provide a second array parameter with schema details.
This library supports serializing associative arrays, normal arrays, adding attributes, and namespaces.
The schema array is a simple format of an associative array where the key is the path/position in the array and the value is an array with schema details.
Associative arrays are the easiest thing to serialize to XML because the format ['key' => 'value'] very naturally
maps to <key>value</key>.
In PHP we represent normal arrays something like ['item1', 'item2', 'item3'], but when serializing to XML
this is a challenge because each element must be wrapped with a tag. This can be done by using the sendItemsAs
element in the schema for a given position. See the example below where the contacts element in the array is an array
of associative arrays. The scheme defines to send each as contact.
A2X also recognizes simple forms of plurals, so if the array data element has a name of contacts and you do not
specify what it's items should be sent as it will strip the trailing s and send each as contact.
If you need to use attributes in your xml, like <contact type="email"><value>[email protected]</value></contact> you can do so
by defining the attributes array in the schema for the position in the XML that needs attributes. The values of the
attributes array in the schema relate to what child elements should be serialized as attributes. This makes it
very natural in the original array to just say:
[
'contact' => [
'type' => 'email',
'value' => '[email protected]',
]
]and in the schema provide:
[
'/path/to/contact' => [
'attributes' => [
'type'
]
]
]See the example below for how /person and /person/contacts/contact have attributes.
If you need to use namespaces in your XML there are two places to define them. First you must provide the actual
namespace definitions, that is the map from namespace prefix to URI. These are provided in the specal @namespaces
element of the schema array. Second, for any given position in the schema array you can specify a namespace
attribute with a single string value that should map to one of the prefixes defined in @attributes. See example
below for how ns1 and ns2 are defined in @attributes and then used for positions
/person/contacts and /person/contacts/contact.
If you want to have all elements at and under a specific position to have the same namespace you can use the
childNamespace attribute in the schema. This will apply the given namespace to all elements below the given
position.
If you need to generate a list of elements without a wrapping parent tag, the schema setting for includeWrappingTag
may be set to false. By default it is considered true if not present. This is useful in the following example
where you have a list of children but want them each listed as a child element instead of as
<children><child></child><child></child></children>.
<?php
use fillup\A2X;
$data = [
'person' => [
'name' => 'Daddio',
'children' => [
[
'name' => 'Older Brother',
],
[
'name' => 'Little Sister',
[
]
]
];
$schema = [
'/person/children' => [
'sendItemsAs' => 'child',
'includeWrappingTag' => false,
],
];
$a2x = new A2X($data, $schema);
$xml = $a2x->asXml();In that example $xml (if formatted) would be:
<?xml version="1.0" encoding="UTF-8"?>
<person>
<name>Daddio</name>
<child>
<name>Older Brother</name>
</child>
<child>
<name>Little Sister</name>
</child>
</person><?php
use fillup\A2X;
$data = [
'person' => [
'attributeName' => 'attribute value',
'name' => [
'given' => 'first',
'surname' => 'last',
],
'address' => [
'street1' => '123 Somewhere',
'street2' => '',
'city' => 'Anytown',
'state' => 'AA',
'country' => 'USA',
],
'age' => 40,
'contacts' => [
[
'type' => 'email',
'value' => '[email protected]',
],
[
'type' => 'mobile',
'value' => '11235551234',
],
],
],
];
$schema = [
'/person' => [
'attributes' => [
'attributeName',
],
],
'/person/contacts' => [
'sendItemsAs' => 'contact',
'namespace' => 'ns1',
'childNamespace' => 'ns2',
],
'/person/contacts/contact' => [
'attributes' => [
'type',
],
],
'@namespaces' => [
'ns1' => 'http://namespaceone.com',
'ns2' => 'http://namespacetwo.com',
],
];
$a2x = new A2X($data, $schema);
$xml = $a2x->asXml();In the above example, $xml will contain the string:
<?xml version="1.0" encoding="UTF-8"?>
<person xmlns:ns1="http://namespaceone.com" xmlns:ns2="http://namespacetwo.com" attributeName="attribute value">
<name>
<given>first</given>
<surname>last</surname>
</name>
<address>
<street1>123 Somewhere</street1>
<street2></street2>
<city>Anytown</city>
<state>AA</state>
<country>USA</country>
</address>
<age>40</age>
<ns1:contacts>
<ns2:contact type="email">
<ns2:value>[email protected]</ns2:value>
</ns2:contact>
<ns2:contact type="mobile">
<ns2:value>11235551234</ns2:value>
</ns2:contact>
</ns1:contacts>
</person>A2X does not currently support pretty printing the xml as is displayed here, but I show it formatted for easier reading.
Contributions are welcome as either issues or even better pull requests. If you like this library and use it, let me know, I'd love to know if others are benefiting from it as well. phillip dot shipley at gmail.
The MIT License (MIT)
Copyright (c) 2016 Phillip Shipley
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.