Docs XMLStreamWriter

Table of Contents Creating XML documents with stubXMLStreamWriter Creating simple documents Importing other streams Importing raw text Available implementations Implementation features Using the net::stubbles::xml::stubXMLStreamWriter factory

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

Please note: this is deprecated since Stubbles 1.1.0 and will be removed with Stubbles 1.2.0. You should get the xml stream writer instance via Stubbles IoC instead of using the xml stream writer 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));