Chris@0: <?php
Chris@0: 
Chris@0: namespace Consolidation\OutputFormatters\StructuredData\Xml;
Chris@0: 
Chris@0: /**
Chris@0:  * When using arrays, we could represent XML data in a number of
Chris@0:  * different ways.
Chris@0:  *
Chris@0:  * For example, given the following XML data strucutre:
Chris@0:  *
Chris@0:  * <document id="1" name="doc">
Chris@0:  *   <foobars>
Chris@0:  *     <foobar id="123">
Chris@0:  *       <name>blah</name>
Chris@0:  *       <widgets>
Chris@0:  *         <widget>
Chris@0:  *            <foo>a</foo>
Chris@0:  *            <bar>b</bar>
Chris@0:  *            <baz>c</baz>
Chris@0:  *         </widget>
Chris@0:  *       </widgets>
Chris@0:  *     </foobar>
Chris@0:  *   </foobars>
Chris@0:  * </document>
Chris@0:  *
Chris@0:  * This could be:
Chris@0:  *
Chris@0:  *  [
Chris@0:  *    'id' => 1,
Chris@0:  *    'name'  => 'doc',
Chris@0:  *    'foobars' =>
Chris@0:  *    [
Chris@0:  *       [
Chris@0:  *         'id' => '123',
Chris@0:  *         'name' => 'blah',
Chris@0:  *         'widgets' =>
Chris@0:  *         [
Chris@0:  *            [
Chris@0:  *              'foo' => 'a',
Chris@0:  *              'bar' => 'b',
Chris@0:  *              'baz' => 'c',
Chris@0:  *            ]
Chris@0:  *         ],
Chris@0:  *       ],
Chris@0:  *    ]
Chris@0:  *  ]
Chris@0:  *
Chris@0:  * The challenge is more in going from an array back to the more
Chris@0:  * structured xml format.  Note that any given key => string mapping
Chris@0:  * could represent either an attribute, or a simple XML element
Chris@0:  * containing only a string value. In general, we do *not* want to add
Chris@0:  * extra layers of nesting in the data structure to disambiguate between
Chris@0:  * these kinds of data, as we want the source data to render cleanly
Chris@0:  * into other formats, e.g. yaml, json, et. al., and we do not want to
Chris@0:  * force every data provider to have to consider the optimal xml schema
Chris@0:  * for their data.
Chris@0:  *
Chris@0:  * Our strategy, therefore, is to expect clients that wish to provide
Chris@0:  * a very specific xml representation to return a DOMDocument, and,
Chris@0:  * for other data structures where xml is a secondary concern, then we
Chris@0:  * will use some default heuristics to convert from arrays to xml.
Chris@0:  */
Chris@0: interface XmlSchemaInterface
Chris@0: {
Chris@0:     /**
Chris@0:      * Convert data to a format suitable for use in a list.
Chris@0:      * By default, the array values will be used.  Implement
Chris@0:      * ListDataInterface to use some other criteria (e.g. array keys).
Chris@0:      *
Chris@0:      * @return \DOMDocument
Chris@0:      */
Chris@0:     public function arrayToXml($structuredData);
Chris@0: }