Creating XML documents with stubXMLStreamWriter

Stubbles provides a unified and simple API to create XML documents, regardless of the XML extensions that you have enabled in PHP. The interface net.stubbles.xml.stubXMLStreamWriter provides the following methods:

interface stubXMLStreamWriter {
    public function __construct($xmlVersion = '1.0', $encoding = 'UTF-8');
    public function getVersion();
    public function getEncoding();
    public function writeStartElement($elementName);
    public function writeEndElement();
    public function writeElement($elementName, array $attributes = array(), $cdata = null);
    public function writeText($data);
    public function writeCData($cdata);
    public function writeComment($comment);
    public function writeProcessingInstruction($target, $data = '');
    public function writeXmlFragment($fragment);
    public function writeAttribute($attributeName, $attributeValue);
    public function importStreamWriter(stubXMLStreamWriter $writer);
    public function asXML();
    public function asDOM();
}

Creating simple documents

To create a new XML document you need to create an instance of a concrete implementation of this interface:

stubClassLoader::load('net::stubbles::xml::stubDomXMLStreamWriter');
$xml = new stubDomXMLStreamWriter();

Then you use the provided methods to write tags, character data, attributes or any other entitity:

$xml->writeStartElement('users');
$xml->writeStartElement('user');
$xml->writeAttribute('id', 'schst');
$xml->writeText('Stephan Schmidt');
$xml->writeEndElement();
$xml->writeStartElement('user');
$xml->writeAttribute('id', 'mikey');
$xml->writeText('Frank Kleine');
$xml->writeEndElement();
$xml->writeEndElement();

To fetch the stream as XML, call the asXML() method:

print $xml->asXML();

This will display:

<?xml version="1.0" encoding="UTF-8"?>
<users>
  <user id="schst">Stephan Schmidt</user>
  <user id="mikey">Frank Kleine</user>
</users>

Importing other streams

It is also possible, to import one stream into the other, like the following example shows:

$xml2 = new stubDomXMLStreamWriter();
$xml2->writeStartElement('group');
$xml2->writeAttribute('id', 'developers');
$xml2->importStreamWriter($xml);
$xml2->writeEndElement();

print $xml2->asXML();

This example will display:

<?xml version="1.0" encoding="UTF-8"?>
<group id="developers">
  <users>
    <user id="schst">Stephan Schmidt</user>
    <user id="mikey">Frank Kleine</user>
  </users>
</group>

Importing raw text

If you have some XML content, that is not generated using the stubXMLStreamWriter API, it can still be imported into a stream using the writeXMLFragment() method.

Available implementations

Currently the following implementations are available:

• net::stubbles::xml::stubDomXMLStreamWriter based on ext/dom
• net::stubbles::xml::stubLibXMLStreamWriter based on ext/xmlwriter

Other implementations will follow.

Implementation features

Not every implementation of net::stubbles::xml::stubXMLStreamWriter must implement every feature. To check, whether the implementation you are using is providing a feature, you may use the hasFeature() method. To check, whether the LibXML-implementation is able to export the XML document as DOM, the following code must be executed:

$xml = new stubLibXMLStreamWriter();
if ($xml->hasFeature(stubXMLStreamWriter::FEATURE_AS_DOM)) {
    print "can export to DOM.";
}

Currently, the following features can be checked:

Feature	Description
FEATURE_AS_DOM	The implementation is able to export the document as DOM.
FEATURE_IMPORT_WRITER	The implementation is able to import another stubXMLStreamWriter

Using the net::stubbles::xml::stubXMLStreamWriter factory

The best way to create a new net::stubbles::xml::stubXMLStreamWriter is to use the net::stubbles::xml::stubXMLStreamWriterFactory instead of directly instantiating the object:

stubClassLoader::load('net::stubbles::xml::stubXMLStreamWriterFactory');
$xml = stubXMLStreamWriterFactory::create('dom');

This will free your code from a dependency to the class name. The factory is also able to create any implementation of the stubXMLStreamWriter interface:

stubClassLoader::load('net::stubbles::xml::stubXMLStreamWriterFactory');
$xml = stubXMLStreamWriterFactory::createAsAvailable();

This method accepts two parameters:

1. An array containing the order of the implementations
2. An array containing the required features

If you prefer the DOM version over the LibXml version, just specify an order:

stubClassLoader::load('net::stubbles::xml::stubXMLStreamWriterFactory');
$xml = stubXMLStreamWriterFactory::createAsAvailable(array('dom', 'xmlwriter'));

If you need any implementation, that is able to import an existing writer, use the following code:

stubClassLoader::load('net::stubbles::xml::stubXMLStreamWriterFactory');
$xml = stubXMLStreamWriterFactory::createAsAvailable(array(), array(FEATURE_IMPORT_WRITER));