xref: /dports/databases/pear-XML_Query2XML/XML_Query2XML-1.7.2/tutorials/XML_Query2XML/XML_Query2XML.pkg

<refentry id="{@id}">
 <refnamediv>
  <refname>XML_Query2XML</refname>
  <refpurpose>Generating XML data from SQL queries</refpurpose>
 </refnamediv>
 <refsynopsisdiv>

  <author>
  	Lukas Feiler
  	<authorblurb>
  	 {@link mailto:lukas.feiler@lukasfeiler.com lukas.feiler@lukasfeiler.com}
  	</authorblurb>
  </author>
  <copyright>Copyright 2006 by Lukas Feiler</copyright>
 </refsynopsisdiv>
 {@toc}
 <refsect1 id="{@id intro}">
  <title>Introduction</title>
  <para>
  	XML_Query2XML allows you to transform the records retrieved with one or more
  	SQL SELECT queries into XML data. Very simple to highly complex
  	transformations are supported. Is was written with performance in mind and
  	can handle large amounts of data. No XSLT needed!
  </para>
  <para>
    Both methods {@link XML_Query2XML::getXML()} and {@link XML_Query2XML::getFlatXML()} return an instance
    of {@link http://www.php.net/manual/en/ref.dom.php#dom.class.domdocument DOMDocument}.
    The class DOMDocument is provided by {@link http://www.php.net/manual/en/ref.dom.php PHP5's built-in DOM API}.
  </para>
 </refsect1>

 <refsect1 id="{@id requirements}">
  <title>Requirements</title>
  <para>
    XML_Query2XML requires
    <itemizedlist>
     <listitem>
      <emphasis>PHP5</emphasis>: XML_Query2XML heavily uses the new exception handling and object orientation features.
     </listitem>
     <listitem>
      <emphasis>PHP5's built-in DOM API</emphasis>
     </listitem>
     <listitem>
      <emphasis>{@link http://www.php.net/PDO PDO} (PHP5's built-in database abstraction class)</emphasis>
      <emphasis>{@link http://pear.php.net/package/DB PEAR DB}</emphasis>,
      <emphasis>{@link http://pear.php.net/package/MDB2 PEAR MDB2}</emphasis> or
      <emphasis>{@link http://adodb.sourceforge.net ADOdb}</emphasis>.
     </listitem>
    </itemizedlist>
    The following packages are optional:
    <itemizedlist>
     <listitem>
      <emphasis>{@link http://pear.php.net/package/I18N_UnicodeString PEAR I18N_UnicodeString}</emphasis>:
      this is only required if you want to use XML_Query2XML's ability to
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_mapper.9075mapping map SQL identifiers to XML names in accordance with ISO/IEC 9075-14:2005}.
     </listitem>
    </itemizedlist>
  </para>
 </refsect1>

 <refsect1 id="{@id migration}">
  <title>Migrating from v0.6.x and v0.7.x to v1.x.x</title>
  <para>
  	The release 0.8.0 of XML_Query2XML is not backward compatible!
  	Due to security considerations XML_Query2XML does not use the
  	native function eval() anymore. Therefore
    <itemizedlist>
     <listitem>
      the "!" prefix is not supported anymore; this affects
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications},
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_value},
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn},
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes} and
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification Complex Query Specifications}
     </listitem>
     <listitem>
      the behaviour of {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_condition} was changed
     </listitem>
     <listitem>
      the new callback prefix "#" was added (use it instead of the "!" prefix)
     </listitem>
    </itemizedlist>
  </para>
  <para>
    Proposed migration strategy:
    <itemizedlist>
     <listitem>
      Wherever you currently use the "!" prefix, use the new callback prefix "#" instead.
      The first argument passed to the callback function/method is always the current record ($record).
      You can supply additional static arguments by placing them within the braces, e.g.
      'MyClass:myMethod(arg2, arg3)' will result in MyClass:myMethod() being called with the current
      record as the first, the string 'arg2' as the second and 'arg3' as the third argument. In
      most cases you will want to put whatever code you used after the "!" prefix into a
      separate function or static method. That function/method is what you call using the callback prefix "#".
     </listitem>
     <listitem>
      The migration for {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_condition} works
      similarly. Move the PHP code into a separate function/method and call it using the callback
      prefix "#".
     </listitem>
    </itemizedlist>
  </para>
 </refsect1>

 <refsect1 id="{@id query2xml_factory}">
  <title>XML_Query2XML::factory()</title>
  <para>
    {@link XML_Query2XML::factory() XML_Query2XML::factory}($db)
  </para>
  <para>
   This is the factory method that will return a new instance of {@link XML_Query2XML}.
   The argument passed to the factory method can be an instance of
   {@link http://www.php.net/PDO PDO},
   {@link http://pear.php.net/package/DB PEAR DB},
   {@link http://pear.php.net/package/MDB2 PEAR MDB2},
   {@link http://adodb.sourceforge.net ADOdb},
   {@link http://pear.php.net/package/Net_LDAP PEAR Net_LDAP},
   {@link http://pear.php.net/package/Net_LDAP2 PEAR Net_LDAP2} or
   any class that extends {@link XML_Query2XML_Driver}
  </para>
  <refsect2 id="{@id database_drivers}">
   <title>Database Drivers for PDO, PEAR MDB2, PEAR DB, ADOdb</title>
   <para>
    XML_Query2XML has drivers for the database abstraction layers PDO, PEAR MDB2, PEAR DB and ADOdb.
   </para>
   <para>
    Using PDO with XML_Query2XML works like this:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
$pdo = new PDO('mysql://root@localhost/Query2XML_Tests');
$query2xml = XML_Query2XML::factory($pdo);
?>
    ]]>
    </programlisting>
   </para>
   <para>
    Using MDB2 with XML_Query2XML works like this:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$mdb2 = MDB2::factory('mysql://root@localhost/Query2XML_Tests');
$query2xml = XML_Query2XML::factory($mdb2);
?>
    ]]>
    </programlisting>
   </para>
   <para>
    The same thing with PEAR DB looks like that:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'DB.php';
$db = DB::connect('mysql://root@localhost/Query2XML_Tests');
$query2xml = XML_Query2XML::factory($db);
?>
    ]]>
    </programlisting>
   </para>
   <para>
    And again the same thing with ADOdb:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'adodb/adodb.inc.php';
//require_once 'adodb/adodb-exceptions.inc.php';
//require_once 'adodb/adodb-pear.inc.php';
$adodb = ADONewConnection('mysql');
$adodb->Connect('localhost', 'root', '', 'Query2XML_Tests');
$query2xml = XML_Query2XML::factory($adodb);
?>
    ]]>
    </programlisting>
    Note that XML_Query2XML works with ADOdb with the default error handling (no additional include file),
    error handling using exceptions (adodb-exceptions.inc.php) and error handling using PEAR_Error
    (adodb-pear.inc.php).
   </para>
   <para>
    I would recommend using MDB2 as it can be considered more advanced than DB
    and much better designed and documented than ADOdb. MDB2 also provides more
    flexibility than PDO. If you want to access a SQLite 3 database use PDO - MDB2
    does only support SQLite 2 as of this writing.
    But use whichever you like - XML_Query2XML works with all of them.
    For the sake of simplicity all the examples will use PEAR MDB2.
   </para>
  </refsect2>
  <refsect2 id="{@id ldap_driver}">
   <title>LDAP Driver for PEAR Net_LDAP</title>
   <para>
    Since v1.6.0RC1 XML_Query2XML comes with a driver for {@link http://pear.php.net/package/Net_LDAP PEAR Net_LDAP}.
    The driver for {@link http://pear.php.net/package/Net_LDAP2 PEAR Net_LDAP2} is available since v1.7.0RC1.
   </para>
   <para>
    Using Net_LDAP(2) with XML_Query2XML works like this:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
$ldap = Net_LDAP::connect(
    'host'     => 'ldap.example.com',
    'port'     => 389,
    'version'  => 3,
    'starttls' => true,
    'binddn'   => 'cn=Manager,ou=people,dc=example,dc=com',
    'bindpw'   => 'secret'
);
$query2xml = XML_Query2XML::factory($ldap);
?>
    ]]>
    </programlisting>
    The driver for Net_LDAP(2) uses a diffrent format for
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.sql}. Instead of
    a string it expects an associative array with the following elements:
    <itemizedlist>
     <listitem>
      <emphasis>'base'</emphasis>: the base search DN
     </listitem>
     <listitem>
      <emphasis>'filter'</emphasis>: the query filter that determines which results are returned
     </listitem>
     <listitem>
      <emphasis>'options'</emphasis>: an array of configuration options for the current query
     </listitem>
    </itemizedlist>
    More information on how to use the LDAP drivers can be found under
    {@tutorial XML_Query2XML.pkg#ldap}
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="{@id query2xml_getflatxml}">
  <title>XML_Query2XML::getFlatXML()</title>
  <para>
    {@link XML_Query2XML::getFlatXML() XML_Query2XML::getFlatXML}($sql, $rootTagName = 'root', $rowTagName = 'row')
  </para>
  <para>
    This method transforms the data retrieved by a single SQL query into flat XML data. Pass the SQL SELECT statement
    as first, the root tag's name as second and the row tag's name as third argument.
  </para>
  <para>
    In most cases you will want to use {@tutorial XML_Query2XML.pkg#query2xml_getxml} instead.
    Please see {@tutorial XML_Query2XML.pkg#casestudies.case01} for an example usage of getFlatXML().
  </para>
 </refsect1>

 <refsect1 id="{@id query2xml_getxml}">
  <title>XML_Query2XML::getXML()</title>
  <para>
    {@link XML_Query2XML::getXML() XML_Query2XML::getXML}($sql, $options)
  </para>
  <para>
  	This method is the most powerful transformation method. It returns an instance of
  	DOMDocument (part of PHP5's built-in DOM API). The records returned by the query/queries will be processed
  	one after another. The $options argument is a rather complex, associative,
  	multi dimensional array. The $sql argument can be a string or as well an associative array.
  </para>

  <refsect2 id="{@id sql}">
   <title>$sql</title>
   <para>
    This option is almost exactly like {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}: you
    can specify the query with a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.simplequeryspecification}
    or a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification}.
    What is different from {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql} is that
    you can also specify a boolean value of false.
   </para>
   <para>
    Here is an example of a simple query specification (<emphasis>WARNING:</emphasis> to prevent SQL injection
    vulerabilities you should use a complex query specification when dealing with non-static queries like this one):
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
if (isset($_REQUEST['artistid']) && is_numeric($_REQUEST['artistid'])) {
    $artistid =  $_REQUEST['artistid'];
} else {
    $artistid = 1;
}
$dom = $query2xml->getXML(
  "SELECT * FROM artist WHERE artistid = $artistid",
  array(
    'rootTag' => 'favorite_artist',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'name',
        'birth_year',
        'music_genre' => 'genre'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    With simple query specifications you have to prevent SQL injection yourself. Here I ensured
    that $artistid is numeric by calling is_numeric().
   </para>
   <para>
    Next we use a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification}
    and prevent SQL injections by using PDO's/MDB2's/DB's/ADOdb's prepare() and execute() methods.
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$artistid = $_REQUEST['artistid'];
$dom = $query2xml->getXML(
  array(
    'data' => array(
        ":$artistid"
    ),
    'query' => 'SELECT * FROM artist WHERE artistid = ?'
  ),
  array(
    'rootTag' => 'favorite_artist',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
      'name',
      'birth_year',
      'music_genre' => 'genre'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    The resulting XML data is identical in both cases (given that artistid was submitted as 1):
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artist>
  <artist>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <music_genre>Soul</music_genre>
  </artist>
</favorite_artist>
    ]]>
    </programlisting>
   </para>
   <para>
    As stated above $sql can also be a boolean value of false. This will only be useful in
    scenarios where you want to combine the results of multiple unrelated queries into
    a single XML document. XML_Query2XML will deal with an $sql argument that has a value
    of false as if it executed a query that returned a single record with no colunns.
   </para>
   <para>
    If you simpy wanted all the records of the table "album" and all
    the records of the table "artist" you could write code like this:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';

$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

$dom = $query2xml->getXML(
    false,
    array(
        'idColumn' => false,
        'rowTag' => '__tables',
        'rootTag' => 'music_store',
        'elements' => array(
            'artists' => array(
                'rootTag' => 'artists',
                'rowTag' => 'artist',
                'idColumn' => 'artistid',
                'sql' => 'SELECT * FROM artist',
                'elements' => array(
                    '*'
                )
            ),
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'sql' => 'SELECT * FROM album',
                'elements' => array(
                    '*'
                )
            )
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    In this case we actually are not interested in $sql at all; all we want is to get our
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}s executed.
    Also note that we used '__tables' for {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_rowtag}
    at the root level: this is because we don't have anything to loop over at the root level - remember
    using false for $sql is like using a query that returns a single record with no columns.
   </para>
   <para>
    The resulting XML looks like this:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_store>
  <artists>
    <artist>
      <artistid>1</artistid>
      <name>Curtis Mayfield</name>
      <birth_year>1920</birth_year>
      <birth_place>Chicago</birth_place>
      <genre>Soul</genre>
    </artist>
    <artist>
      <artistid>2</artistid>
      <name>Isaac Hayes</name>
      <birth_year>1942</birth_year>
      <birth_place>Tennessee</birth_place>
      <genre>Soul</genre>
    </artist>
    <artist>
      <artistid>3</artistid>
      <name>Ray Charles</name>
      <birth_year>1930</birth_year>
      <birth_place>Mississippi</birth_place>
      <genre>Country and Soul</genre>
    </artist>
  </artists>
  <albums>
    <album>
      <albumid>1</albumid>
      <artist_id>1</artist_id>
      <title>New World Order</title>
      <published_year>1990</published_year>
      <comment>the best ever!</comment>
    </album>
    <album>
      <albumid>2</albumid>
      <artist_id>1</artist_id>
      <title>Curtis</title>
      <published_year>1970</published_year>
      <comment>that man's got somthin' to say</comment>
    </album>
    <album>
      <albumid>3</albumid>
      <artist_id>2</artist_id>
      <title>Shaft</title>
      <published_year>1972</published_year>
      <comment>he's the man</comment>
    </album>
  </albums>
</music_store>
    ]]>
    </programlisting>
   </para>
   <para>
    Want to dump not just two but all of your table? Have a look at
    {@tutorial XML_Query2XML.pkg#dumpdatabase}.
   </para>
  </refsect2>

  <refsect2 id="{@id options_elements}">
   <title>$options['elements']</title>
   <para>
    This option is an array that basically holds column names to include in the XML data as child
    elements. There are two types of element specifications:
    <itemizedlist>
     <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}
     </listitem>
     <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}
     </listitem>
    </itemizedlist>
   </para>
   <refsect3 id="{@id simple_element_specifications}">
    <title>Simple Element Specifications</title>
    <para>
      These allow you to use an array to specify elements that have only two properties: a name and a value.
      The array values are used to specify the XML element values whereas the array keys are used to specify the
      XML element names. For all array elements that are defined without a key, the array values will be used for
      the XML element names. If no prefix is used (see below) the contents of the array values are interpreted
      as column names. The following example illustrates the most basic usage of a simple element specification:
      <programlisting role="php">
      <![CDATA[
array(
    'COLUMN1',
    'COLUMN2'
);
      ]]>
      </programlisting>
      This might result in XML data like this:
      <programlisting role="tutorial">
      <![CDATA[
<COLUMN1>this was the contents of COLUMN1</COLUMN1>
<COLUMN2>this was the contents of COLUMN2</COLUMN2>
      ]]>
      </programlisting>
      If you do not want your XML elements named after your database columns you have to work with array keys
      (ELEMENT1 and ELEMENT2 in our example):
      while the element specification
      <programlisting role="php">
      <![CDATA[
array(
    'ELEMENT1' => 'COLUMN1',
    'ELEMENT2' => 'COLUMN2'
);
      ]]>
      </programlisting>
      This would make the same data appear like this:
      <programlisting role="tutorial">
      <![CDATA[
<ELEMENT1>this was the contents of COLUMN1</ELEMENT1>
<ELEMENT2>this was the contents of COLUMN2</ELEMENT2>
      ]]>
      </programlisting>
    </para>
    <para>
      If you use both, the array key and the array value to specify an XML element, the array value can be of the following types:
      <itemizedlist>
       <listitem>
        <emphasis>COLUMN NAME (string)</emphasis>: this is the default if not preceeded by ':' or '#'.
        If the column does not exist, an {@link XML_Query2XML_ConfigException} will be thrown.
       </listitem>
       <listitem>
        <emphasis>STATIC TEXT with a : prefix (string)</emphasis>: if the value is preceeded by a colon (':'), it is
        interpreted as static text.
       </listitem>
       <listitem>
        <emphasis>CALLBACK FUNCTION with a # prefix (string)</emphasis>: if the value is preceeded by a pound sign ('#'), it
        is interpreted as a callback function. You can use a regular function (e.g. '#myFunction()') or a static
        method (e.g. '#MyClass::myFunction()') - for how to use a non-static method, see the type COMMAND OBJECT.
        The current record will be passed to the callback function
        as an associative array. You can also pass additional string arguments to the callback function by specifing
        them within the opening and closing brace; e.g. '#Utils::limit(12)' will result in Util::limit() being
        called with the current record as the first and '12' as the second argument. If you do not want
        to pass additional arguments to the callback function, the opening and closing brace are optional.
        The callback function's return value will be converted to a string and used as the child text node
        if it is anything but an object or an array. If you do return an object or an array from a callback
        function it has to be an instance of {@link http://www.php.net/manual/en/ref.dom.php DOMNode} or
        an array of DOMNode instances. Please see {@tutorial XML_Query2XML.pkg#other_xml_data_sources} for examples
        and further details. If an instances of any other class is returned, a XML_Query2XML_XMLException will be thrown.
       </listitem>
       <listitem>
        <emphasis>COMMAND OBJECT (object)</emphasis>: If you want to use a non-static method as a
        callback function, you can do so by specifying the value as an instance of a class that
        implements the {@link XML_Query2XML_Callback} interface. This implementation of the
        {@link http://en.wikipedia.org/wiki/Command_pattern command pattern} gives you all the
        flexibility. The disadvantage ist that you cannot use the XML UNSERIALIZATION prefix
        or the CONDITIONAL prefix. Note: you have to require_once 'XML/Query2XML/Callback.php'
        before using the XML_Query2XML_Callback interface. The return value of a COMMAND OBJECT's
        execute() method is treated exactly the same as the return value of a CALLBACK FUNCTION.
       </listitem>
      </itemizedlist>
      There are four more prefixes available that can be used in conjunction with all the prifixes described above:
      <itemizedlist>
       <listitem>
        <emphasis>XML UNSERIALIZATION prefix &amp;</emphasis>: the ampersand (&amp;) prefix allows you to
        automatically unserialize string data, i.e. transform a string into a {@link http://www.php.net/manual/en/ref.dom.php DOMDocument}. DOMDocument's
        {@link http://www.php.net/manual/en/function.dom-domdocument-loadxml.php loadXML()} method will be
        used for this purpose. You can combine all three types with this prefix: '&amp;COLUMN_NAME',
        '&amp;#function()' or '&amp;:&lt;name&gt;John&lt;/name&gt;' will all work. You can even use the CONDITIONAL prefix
        which has to preceed all other prefixes. If the data cannot be unserialized i.e.
        {@link http://www.php.net/manual/en/function.dom-domdocument-loadxml.php DOMDocument::loadXML()}
        returns false, a XML_Query2XML_XMLException will be thrown. Please see
        {@tutorial XML_Query2XML.pkg#other_xml_data_sources} for examples and further
        details.
       </listitem>
       <listitem>
        <emphasis>BASE64 ENCODING prefix ^</emphasis>: if the specification starts with a carrat sign ('^'),
        the element value will be passed to {@link http://www.php.net/base64_encode base64_encode()}.
        The BASE64 ENCODING prefix can be used with all the prefixes described above (just put the BASE64 ENCODING prefix first):
        e.g. '^#', '^:' or '^COLUMN_NAME'.
       </listitem>
       <listitem>
        <emphasis>CDATA SECTION prefix =</emphasis>: if the specification starts with an equal sign ('='),
        the element value will be enclosed in a CDATA section. A CDATA section starts with
        "&lt;![CDATA[" and ends with "]]&gt;".
        The CDATA SECTION prefix can be used with all the prefixes described above (just put the CDATA SECTION prefix first):
        e.g. '=#', '=:', '=COLUMN_NAME' or '=^'.
       </listitem>
       <listitem>
        <emphasis>CONDITIONAL prefix ?</emphasis>: if the specification starts with a question mark ('?'),
        the whole element will be skipped if the value equals (==) an empty string. The CONDITIONAL prefix
        can be combined with all types described above: if you do this you have to write the CONDITIONAL
        prefix first e.g. '?#', '?:', '?&amp;', '?=', '?^', or '?COLUMN_NAME'.
       </listitem>
      </itemizedlist>
      Note: for ovious reasons, the prefix cannot be combined with a COMMAND OBJECT.
    <para>
    </para>
      Basically, the same syntax can be use for
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_value},
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes},
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification} and
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn} because the private method
      {@link XML_Query2XML::_applyColumnStringToRecord()} is used in all cases.
    </para>
    <para>
      Let's start out with a very simple example. It will use
      the column name as the XML element name for the first two columns but the
      custom element name 'music_genre' for the column 'genre':
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'name',
        'birth_year',
        'music_genre' => 'genre'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
      This results in the following XML data:
      <programlisting role="tutorial">
      <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <music_genre>Soul</music_genre>
  </artist>
  <artist>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <music_genre>Soul</music_genre>
  </artist>
  <artist>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <music_genre>Country and Soul</music_genre>
  </artist>
</favorite_artists>
      ]]>
      </programlisting>
     </para>

     <para>
     The following example demonstrates the usage of all different types:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/Callback.php';
require_once 'MDB2.php';

class Utils
{
    function trim($record, $columnName)
    {
        return trim($record[$columnName]);
    }

    function getPublishedYearCentury($record)
    {
        return floor($record['published_year']/100);
    }
}

class ToLowerCallback implements XML_Query2XML_Callback
{
    private $_columnName = '';

    public function __construct($columnName)
    {
        $this->_columnName = $columnName;
    }

    public function execute(array $record)
    {
        return strtolower($record[$this->_columnName]);
    }
}

$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT
    *
   FROM
    sale,
    store,
    album
   WHERE
    sale.store_id = store.storeid
    AND
    sale.album_id = album.albumid
    AND
    sale.timestamp < '2005-06-01'",
  array(
    'rootTag' => 'sales',
    'idColumn' => 'saleid',
    'rowTag' => 'sale',
    'elements' => array(
        'saleid',
        'sale_timestamp' => 'timestamp',
        'static' => ':some static text',
        'now' => ':' . time(),
        'album_century' => '#Utils::getPublishedYearCentury()',
        'album_title' => '?#Utils::trim(title)',
        'album_comment' => new ToLowerCallback('comment'),
        'storeid',
        'store_building1' => '?&building_xmldata',
        'store_building2' => '?=building_xmldata',
        'store_building3' => '?^building_xmldata'
    )
  )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
      Let's go through all simple element specifications, one by one:
      <itemizedlist>
       <listitem>
        <emphasis>'saleid'</emphasis>: this is as simple as it can get. The value of the column saleid will be used for an element named saleid.
       </listitem>
       <listitem>
        <emphasis>'sale_timestamp' => 'timestamp'</emphasis>: here we want to place the value of the
        column timestamp in an element named sale_timestamp; we therefore use sale_timestamp as the array key.
       </listitem>
       <listitem>
        <emphasis>'static' => ':some static text'</emphasis>: the STATIC TEXT (note the ":" prefix) "some static text" will be placed inside an element named static.
       </listitem>
       <listitem>
        <emphasis>'now' => ':' . time()</emphasis>: here the static text is computed at run time; however it will be the same for all "now" elements.
       </listitem>
       <listitem>
        <emphasis>'album_century' => '#Utils::getPublishedYearCentury()'</emphasis>: here we use
        a CALLBACK FUNCTION with a "#" prefix; the return value of Utils::getPublishedYearCentury() is used as the XML element value.
        Note that the callback function will automatically be called with the current $record as the first argument.
       </listitem>
       <listitem>
        <emphasis>'album_title' => '?#Utils::trim(title)'</emphasis>: we also use a CALLBACK FUNCTION with a "#" prefix, but
        this time we pass an additional string argument to our callback function by specifing it within the opening and
        closing brace. Also, we use the CONDITIONAL prefix ? which means that the album_title element will only appear in
        the generated XML data if Utils::trim() returned a non-empty string (to be precise a string that != "").
       </listitem>
       <listitem>
        <emphasis>'album_comment' => new ToLowerCallback('comment')</emphasis>: here we use a COMMAND OBJECT implementing
        the {@link XML_Query2XML_Callback} interface. This is the object oriented way to use callbacks! Note how we pass the
        column name to the callback class constructor, so that it's execute() method will now what column to work on.
       </listitem>
       <listitem>
        <emphasis>'storeid'</emphasis>: plain an simple again
       </listitem>
       <listitem>
        <emphasis>'store_building1' =>  '?&amp;building_xmldata'</emphasis>: here we use the XML UNSERIALIZATION prefix "&amp;"
        to transform the value of the building_xmldata column into a DOMDocument. Using the CONDITIONAL prefix ? means
        that store_building1 will only appear if building_xmldata is non-empty (!= "" to be precise).
       </listitem>
       <listitem>
        <emphasis>'store_building2' => '?=building_xmldata'</emphasis>: CDATA SECTION prefix "=" is another way
        incorporate XML data; the contents of the column building_xmldata will be surrounded by
         "&lt;![CDATA[" and "]]&gt;". Using the CONDITIONAL prefix ? means
        that store_building2 will only appear if building_xmldata is non-empty (!= "" to be precise).
       </listitem>
       <listitem>
        <emphasis>'store_building3' => '?^building_xmldata'</emphasis>: here we use the BASE64 ENCODING prefix "^"
        to first base64-encode the contents of the building_xmldata column. We again use the CONDITIONAL prefix "?".
       </listitem>
      </itemizedlist>
      The resulting XML data looks like this:
      <programlisting role="tutorial">
      <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<sales>
  <sale>
    <saleid>1</saleid>
    <sale_timestamp>2005-05-25 07:32:00</sale_timestamp>
    <static>some static text</static>
    <now>1187498966</now>
    <album_century>19</album_century>
    <album_title>New World Order</album_title>
    <album_comment>the best ever!</album_comment>
    <storeid>1</storeid>
    <store_building1>
      <building>
        <floors>4</floors>
        <elevators>2</elevators>
        <square_meters>3200</square_meters>
      </building>
    </store_building1>
    <store_building2>< ![CDATA[<building><floors>4</floors><elevators>2</elevators><square_meters>3200</square_meters></building>]] ></store_building2>
    <store_building3>PGJ1aWxkaW5nPjxmbG9vcnM+NDwvZmxvb3JzPjxlbGV2YXRvcnM+MjwvZWxldmF0b3JzPjxzcXVhcmVfbWV0ZXJzPjMyMDA8L3NxdWFyZV9tZXRlcnM+PC9idWlsZGluZz4=</store_building3>
  </sale>
  <sale>
    <saleid>11</saleid>
    <sale_timestamp>2005-05-25 07:23:00</sale_timestamp>
    <static>some static text</static>
    <now>1187498966</now>
    <album_century>19</album_century>
    <album_title>Curtis</album_title>
    <album_comment>that man's got somthin' to say</album_comment>
    <storeid>2</storeid>
    <store_building1>
      <building>
        <floors>2</floors>
        <elevators>1</elevators>
        <square_meters>400</square_meters>
      </building>
    </store_building1>
    <store_building2>< ![CDATA[<building><floors>2</floors><elevators>1</elevators><square_meters>400</square_meters></building>]] ></store_building2>
    <store_building3>PGJ1aWxkaW5nPjxmbG9vcnM+MjwvZmxvb3JzPjxlbGV2YXRvcnM+MTwvZWxldmF0b3JzPjxzcXVhcmVfbWV0ZXJzPjQwMDwvc3F1YXJlX21ldGVycz48L2J1aWxkaW5nPg==</store_building3>
  </sale>
</sales>
      ]]>
      </programlisting>
      Note: due to a bug in phpDocumentor I had to cheat a little bit in the above XML; as you might have noticed
      there was a space between "&lt;" and "![CDATA[".
     </para>
    </refsect3>
    <refsect3 id="{@id complex_element_specifications}">
     <title>Complex Element Specifications</title>
     <para>
      A complex element specification consists of an array that can have all options
      that can be present on the root level plus {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}
      and {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options}.
      This allows for complete (and theoretically infinite) nesting. You will need to use it if the
      child element should have attributes or child elements.
     </para>
     <para>
      The following example is like the first one in
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}
      with one difference: the XML element 'name' should have the attribute 'type' set to the
      static value 'full_name'. As attributes are not supported by simple elements specifications,
      we have to use a complex element specification for the element 'name':
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'name' => array(
            'value' => 'name',
            'attributes' => array(
                'type' => ':full_name'
            )
        ),
        'birth_year',
        'music_genre' => 'genre'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
      This results in the following XML data:
      <programlisting role="tutorial">
      <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist>
    <name type="full_name">Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <music_genre>Soul</music_genre>
  </artist>
  <artist>
    <name type="full_name">Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <music_genre>Soul</music_genre>
  </artist>
  <artist>
    <name type="full_name">Ray Charles</name>
    <birth_year>1930</birth_year>
    <music_genre>Country and Soul</music_genre>
  </artist>
</favorite_artists>
      ]]>
      </programlisting>
      </para>
      <para>
       Here is another little example:
       <programlisting role="php">
       <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT * FROM artist LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
              'rootTag' => 'albums',
              'rowTag' => 'album',
              'idColumn' => 'albumid',
              'elements' => array('albumid', 'title', 'published_year')
            )
        )
    )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
      This results in the following XML data:
      <programlisting role="tutorial">
      <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>1</albumid>
        <title>New World Order</title>
        <published_year>1990</published_year>
      </album>
      <album>
        <albumid>2</albumid>
        <title>Curtis</title>
        <published_year>1970</published_year>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>3</albumid>
        <title>Shaft</title>
        <published_year>1972</published_year>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
    <albums />
  </artist>
</music_library>
      ]]>
      </programlisting>
     </para>
     <para>
      As we want for every artist only a single tag we need to identify each artist by the primary
      key of the table artist. Note that there is a second record for Curtis Mayfield (related to
      the album Curtis), but we don't want something like
      <programlisting role="tutorial">
      <![CDATA[
<artist>
  <name>Curtis Mayfield</name>
  <album>
    <name>New World Order</name>
  </album>
</artist>
<artist>
  <name>Curtis Mayfield</name>
  <album>
    <name>Curits</name>
  </album>
</artist>
      ]]>
      </programlisting>
      but rather
      <programlisting role="tutorial">
      <![CDATA[
<artist>
  <name>Curtis Mayfield</name>
  <albums>
    <album>
     <name>New World Order</name>
    </album>
    <albums>
     <name>Curtis</name>
    </albums>
  </albums>
</artist>
      ]]>
      </programlisting>
      This is achieved by telling XML_Query2XML which entity to focus on (on this level): the artist, as it
      is identified by the artist table's primary key. Once XML_Query2XML get's to the second Curtis Mayfield
      record, it can tell by the artistid 1 that an XML element was already created for this artist.
     </para>
     <para>
      For a one more example and a detailed explanation of complex child elements that have
      child elements themselves, see {@tutorial XML_Query2XML.pkg#casestudies.case02}.
      For an advanced example, see {@tutorial XML_Query2XML.pkg#casestudies.case05}.
     </para>
    </refsect3>
    <refsect3 id="{@id asterisk_shortcut}">
     <title>Using the Asterisk Shortcut</title>
     <para>
      The asterisk shortcut only works with {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}
      (and {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications}).
     </para>
     <para>
      In some scenarios you will just want to use all columns found in the result set
      for {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}.
      This is where the asterisk shortcut can come in very handy. An element specification that
      contains an asterisk (an "asterisk element specification") will be duplicated for each
      column present in the result set ($record). The simplest way of using the asterisk shortcut is this:
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        '*'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
      As the result set contains the column artistid, name, birth_year, birth_place and genre the XML data will look like this:
      <programlisting role="tutorial">
      <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
  </artist>
</favorite_artists>
      ]]>
      </programlisting>
      This is because internally, the array
      <programlisting role="php">
      <![CDATA[
'elements' => array(
  '*'
)
      ]]>
      </programlisting>
      is expanded to
      <programlisting role="php">
      <![CDATA[
'elements' => array(
  'artistid',
  'name',
  'birth_year',
  'birth_place',
  'genre'
)
      ]]>
      </programlisting>
     </para>
     <para>
      Think of the asterisk as a variable that will get replaced with each column name found in the result set:
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'TAG_*' => '#padWithHyphens(*)'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();

function padWithHyphens($record, $columnName)
{
    return '--' . $record[$columnName] . '--';
}
?>
      ]]>
      </programlisting>
      The above code would result in the following data:
      <programlisting role="tutorial">
      <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist>
    <TAG_artistid>--1--</TAG_artistid>
    <TAG_name>--Curtis Mayfield--</TAG_name>
    <TAG_birth_year>--1920--</TAG_birth_year>
    <TAG_birth_place>--Chicago--</TAG_birth_place>
    <TAG_genre>--Soul--</TAG_genre>
  </artist>
  <artist>
    <TAG_artistid>--2--</TAG_artistid>
    <TAG_name>--Isaac Hayes--</TAG_name>
    <TAG_birth_year>--1942--</TAG_birth_year>
    <TAG_birth_place>--Tennessee--</TAG_birth_place>
    <TAG_genre>--Soul--</TAG_genre>
  </artist>
  <artist>
    <TAG_artistid>--3--</TAG_artistid>
    <TAG_name>--Ray Charles--</TAG_name>
    <TAG_birth_year>--1930--</TAG_birth_year>
    <TAG_birth_place>--Mississippi--</TAG_birth_place>
    <TAG_genre>--Country and Soul--</TAG_genre>
  </artist>
</favorite_artists>
      ]]>
      </programlisting>
     </para>
     <para>
      You can also combine a simple element specification containing an asterisk shortcut with other (simple and complex) element specifications.
      The additional element specifications will be treated as an exception to the general rule set up by the asterisk element specification.
      The following code will produce a tag for each column in the result set containing the column's value. The only exeption is the column
      "genre" which we want to be different: the value should be all uppercase:
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        '*' => '*',
        'genre' => '#genre2uppercase()'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();

function genre2uppercase($record)
{
    return strtoupper($record['genre']);
}
?>
      ]]>
      </programlisting>
      The resulting XML data looks like this:
      <programlisting role="tutorial">
      <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>SOUL</genre>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>SOUL</genre>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>COUNTRY AND SOUL</genre>
  </artist>
</favorite_artists>
      ]]>
      </programlisting>
      This is because internally, the array
      <programlisting role="php">
      <![CDATA[
'elements' => array(
  '*' => '*',
  'genre' => '#genre2uppercase()'
)
      ]]>
      </programlisting>
      is expanded to
      <programlisting role="php">
      <![CDATA[
'elements' => array(
  'artistid',
  'name',
  'birth_year',
  'birth_place',
  'genre' => '#genre2uppercase()'
)
      ]]>
      </programlisting>
      Please keep in mind that this also applies when combining an asterisk element specification with a complex element specification.
      That's why the following code would produce exactly the same XML data:
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        '*' => '*',
        'genre' => array(
            'value' => '#genre2uppercase()'
        )
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();

function genre2uppercase($record)
{
    return strtoupper($record['genre']);
}
?>
      ]]>
      </programlisting>
     </para>
     <para>
      If we wanted to include all columns in the XML output except "genre" we could use a little trick:
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        '*' => '*',
        'genre' => '?:'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
      In the resulting XML data the column "genre" is missing because we used the CONDITIONAL prefix '?' in combination with a static empty text:
      <programlisting role="tutorial">
      <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
  </artist>
</favorite_artists>
      ]]>
      </programlisting>
      The exact same result could of course also be achieved using the "condition" option:
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        '*' => '*',
        'genre' => array(
            'condition' => '#returnFalse()'
            //this would also work: 'condition' => ':'
        )
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();

function returnFalse()
{
    return false;
}
?>
      ]]>
      </programlisting>
     </para>
     <para>
      Another example of how to use the asterisk shortcut can be found in
      {@tutorial XML_Query2XML.pkg#casestudies.case07}.
     </para>
     <para>
      One final note on the asterisk shortcut: if you explicitly specify a tag name (an array element key) it has to contain an asterisk. The following code
      would cause a {@link XML_Query2XML_ConfigException} to be thrown:
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'tag' => '*'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
      This is because expanding
      <programlisting role="php">
      <![CDATA[
'elements' => array(
  'tag' => '*'
)
      ]]>
      </programlisting>
      to
      <programlisting role="php">
      <![CDATA[
'elements' => array(
  'tag' => 'artistid',
  'tag' => 'name',
  'tag' => 'birth_year',
  'tag' => 'birth_place',
  'tag' => 'genre'
)
      ]]>
      </programlisting>
      just makes no sense and therfore "*" is treated as a regular column name - which does not exist in this case!
      The exception's message would read: [elements]: The column "*" used in the option "tag" does not exist in the result set.
     </para>
    </refsect3>
  </refsect2>

  <refsect2 id="{@id options_idcolumn}">
   <title>$options['idColumn']</title>
   <para>
    In most cases this will be the name of the column by which a record is identified as unique, aka the
    primary key. This is especially important within a
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications Complex Element Specification}.
    See there for an example. This option is obligatory at the root level! The idColumn specification can be
    of the following types:
    <itemizedlist>
     <listitem>
      <emphasis>COLUMN NAME</emphasis>: this is the default if not preceeded by ':' or '#'.
      If the column does not exist, an {@link XML_Query2XML_ConfigException} will be thrown.
      The current record (not the one of the parent level) will be used.
     </listitem>
     <listitem>
      <emphasis>STATIC TEXT with a : prefix</emphasis>: if the value is preceeded by a colon (':'), it is
      interpreted as static text.
     </listitem>
     <listitem>
      <emphasis>CALLBACK FUNCTION with a # prefix</emphasis>: if the value is preceeded by a pound sign ('#'), it
      is interpreted as a callback function. You can use a regular function (e.g. '#myFunction()') or a static
      method (e.g. '#MyClass::myFunction()') - for how to use a non-static method, see the type COMMAND OBJECT.
      The current record will be passed to the callback function
      as an associative array. You can also pass additional string arguments to the callback function by specifing
      them within the opening and closing brace; e.g. '#Utils::limit(12)' will result in Util::limit() being
      called with the current record as the first and '12' as the second argument. If you do not want
      to pass additional arguments to the callback function, the opening and closing brace are optional.
     </listitem>
     <listitem>
      <emphasis>COMMAND OBJECT (object)</emphasis>: If you want to use a non-static method as a
      callback function, you can do so by specifying the value as an instance of a class that
      implements the {@link XML_Query2XML_Callback} interface. This implementation of the
      {@link http://en.wikipedia.org/wiki/Command_pattern command pattern} gives you all the
      flexibility. Note: you have to require_once 'XML/Query2XML/Callback.php'
      before using the XML_Query2XML_Callback interface. The return value of a COMMAND OBJECT's
      execute() method is treated exactly the same as the return value of a CALLBACK FUNCTION.
     </listitem>
     <listitem>
      <emphasis>FALSE (boolean)</emphasis>: Only use this if you don't have a primary key
      (which is a very bad idea) or you have a very simple tasks at hand like retrieving all
      records from a table. Using the value FALSE will make XML_Query2XML treat every record
      as unique. WARNING: it is considered very bad practice to use a value of
      FALSE if you have a way to specify your primar key. This is because your code might
      change over time and having your primary key specified will just make your more stable.
      For a legitimate use of the value FALSE for the option idColumn, please see
      {@tutorial XML_Query2XML.pkg#dumpdatabase}.
     </listitem>
    </itemizedlist>
    The same syntax (with the additional '?' prefix but without the boolean value FALSE) can
    be use for
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_value},
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications},
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification} and
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications} because the private method
    {@link XML_Query2XML::_applyColumnStringToRecord()} is used in all cases.
   </para>
   <para>
    For example and further discussion of {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn}
    please see {@tutorial XML_Query2XML.pkg#casestudies.case02}.
   </para>
   <refsect3 id="{@id multicolumn_pk}">
    <title>Handling Multi-Column Primary Keys</title>
    <para>
     Sometimes your primary key will consist of multiple columns. For example, this might
     be the case when you implement a many-to-many relationship using an intersection table.
    </para>
    <para>
     But as you know by now,
     $options['idColumn'] has to evaluate to one unique ID for every record.
     Depending on the type of the primary key columns you will want to choose a different strategy to
     compute that unique ID for every record. To begin with, you have to choose whether
     you want to compute that unique ID within the database or using PHP. To do it within the
     database you will have to define an alias using the "... AS alias_name" syntax. Using
     PHP you have to use a callback function to generate the ID. When generating the ID, you
     again have different options.
    </para>
    <para>
     If your primary key columns are of a numeric type, you can
     <itemizedlist>
      <listitem>
       Concatenate your primary key columns using a separator. In the database
       you would use something like "CONCAT(column1, '_', column2) AS id" and
       when implemented in PHP you would write a callback that returns something
       like "$record['column1'] . '_' . $record['column2']".
      </listitem>
      <listitem>
       If Leftshift the first column by the number of bits the second column consumes
       and OR the leftshifted first column with the second column. E.g. if you had
       two columns defined as TINYINT UNSIGNED (0 to 255, i.e. 8 bits), you could
       generate the ID by
       <programlisting role="php">
       <![CDATA[
$id = ($column1 << 8) | $column2;
       ]]>
       </programlisting>
       Think of like this:
       <![CDATA[
$column1 (set to 255):           00000000000000000000000011111111
$column2 left-shifted by 8 bits: 00000000000000001111111100000000

now we OR the left-shifted $column1 with $column2 (both were
originally set to the maximum of 255):
$column1 (left-shifted 255): 00000000000000001111111100000000
$column2 (set to 255):       00000000000000000000000011111111
-------------------------------------------------------------
result:                      00000000000000001111111111111111
As you can see two different combinations of $column1 and $column2
will always result in a different ID. This is because the left-shifted
$column1 does not intersect with $column2.
       ]]>
       <emphasis>WARNING: an integer in PHP has 32 bits</emphasis> -
       the tecnique described above therefore only works if the sum
       of the bits consumed by your primary key columns is less than
       or equal to 32 (i.e. two 16 bit numbers, four 8 bit numbers or
       two 8 bit numbers and one 16 bit number).
      </listitem>
      <listitem>
       Use the generateIdFromMultiKeyPK() method described below.
      </listitem>
     </itemizedlist>
    </para>
    <para>
     If your primary key columns are of a character type (e.g. CHAR, VARCHAR) you
     have to come up with something else. Before you read on, I strongly urge
     you to reconsider your choice for the primary key (does it really meet the
     requirements of minimality and stability, i.e. is immutable?).
     <emphasis>SECURITY WARNING:</emphasis>
     Do not simply concatenate your character type columns (with or without a separator).
     The following example shows why:
     <![CDATA[
record1: column1='a_b' column2='c'
record2: column1='a'   column2='b_c'
When using the separator '_' both records would have an ID of 'a_b_c'.
     ]]>
     A malicious attacker could use your separator within
     one of the column values to force ID collisions, which potentially
     lead to an exploitable security vulnerability. Great care should therefore
     be taken when choosing a separator - and relying on its confidentiality is
     not a good strategy. What you might do is to use a separator that is longer
     than the maximum character length of your primary key columns. But this only
     makes sense if that maximum is rather low. For example, if you have two CHAR(2)
     columns, it is reasonable to use the separator '---' which is three characters long.
    </para>
    <para>
     Another thing one might think of is to use a hash function like sha1() or md5().
     But that's not really an option as it would really kill the performance of your
     application.
    </para>
    <para>
     The most bullet proof solution to the problem of generating a unique ID from
     two character type columns is to use a callback function that works with
     an array. The following function can be used as a callback whenever
     you need to generate an ID from two character type columns.
     <programlisting role="php">
     <![CDATA[
<?php
/**Returns a unique ID base on the values stored in
* $record[$columnName1] and $record[$columnName2].
*
* @param array $record An associative array.
* @param string $columnName1 The name of the first column.
* @param string $columnName2 The name of the second column.
* @return int The ID.
*/
function generateIdFromMultiKeyPK($record, $columnName1, $columnName2)
{
    static $ids = array();
    static $idCounter = 0;

    $column1 = $record[$columnName1];
    $column2 = $record[$columnName2];
    if (!isset($ids[$column1])) {
        $ids[$column1] = array();
    }
    if (!isset($ids[$column1][$column2])) {
        $ids[$column1][$column2] = $idCounter++;
    }
    return $ids[$column1][$column2];
}
?>
     ]]>
     </programlisting>
    </para>
    <para>
     All you have to do is to specify $options['idColumn'] as:
     <![CDATA[
'#generateIdFromMultiKeyPK(name_of_column1, name_of_column2)'
     ]]>
     Remember: $record is automatically passed as the first argument
     to the callback function.
    </para>
   </refsect3>
  </refsect2>

  <refsect2 id="{@id options_attributes}">
   <title>$options['attributes']</title>
   <para>
    This option is an array that holds columns to include in the XML data as
    attributes. {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications Simple}
    and {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.complex_attribute_specifications complex} attribute
    specifications are supported.
   </para>
   <para>
    If you want to add attributes to the root element (i.e. the first child of the DOMDocument instance returned by {@link XML_Query2XML::getXML() getXML()}),
    please see {@tutorial XML_Query2XML.pkg#query2xml_getxml.return_value_modification}.
   </para>
   <refsect3 id="{@id simple_attribute_specifications}">
    <title>Simple Attribute Specifications</title>
    <para>
     It works like
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}:
     the column names are the array values. By default the column's value
     will be put into an attribute named after the column. If you're
     unhappy with the default you can specify an other attribute name by using
     it as the array key. As documented for {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}
     the prefixes "?", "#", "^" and ":" or a COMMAND OBJECT can be used. Only the UNSERIALIZATION prefix &amp; and the CDATA SECTION prefix ^ which are valid for
     a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications Simple Element Specification}
     cannot be used for a Simple Attribute Specification.
    </para>
    <para>
     The follwing example will use
     the column name as the attribute name for the first two columns but the
     custom attribute name 'music_genre' for the column 'genre':
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(),
    'attributes' => array(
      'name',
      'birth_year',
      'music_genre' => 'genre'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     This results in the following XML data:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist name="Curtis Mayfield" birth_year="1920" music_genre="Soul"/>
  <artist name="Isaac Hayes" birth_year="1942" music_genre="Soul"/>
  <artist name="Ray Charles" birth_year="1930" music_genre="Country and Soul"/>
</favorite_artists>
    ]]>
     </programlisting>
    </para>
   </refsect3>
   <refsect3 id="{@id complex_attribute_specifications}">
    <title>Complex Attribute Specifications</title>
    <para>
     A complex attribute specification consists of an array that must contain
     <itemizedlist>
      <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_value}: the attribute's value
      (note: you cannot use the UNSERIALIZATION prefix &amp; or the the CDATA SECTION prefix ^ for an attribute specification)
      </listitem>
     </itemizedlist>
     and optionally can contain
     <itemizedlist>
      <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_condition}: condition for the inclusion of the attribute
      </listitem>
      <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_encoder}: encoding of the attribute value
      </listitem>
      <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}: allows you to fetch more data
      </listitem>
      <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options}: options for the sql option
      </listitem>
     </itemizedlist>
     The array key used to store the complex attribute specification is always used as the attribute's name.
     Unlike {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}
     complex attribute specifications cannot be nested for obvious reasons. Complex attribute specifications
     should only be used for the following reasons:
     <itemizedlist>
      <listitem>
      the attribute is only to be included under a condition that cannot be expressed using the '?' prefix
      within a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications simple attribute specification}
      </listitem>
      <listitem>
      additional data is needed from the database
      </listitem>
     </itemizedlist>
     In all other cases {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications}
     should be used as they will make your code run faster.
    </para>
    <para>
     To add a "bornBefore1940" attribute only to those artists that were born before 1940 we could write:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'attributes' => array(
      'name',
      'birth_year',
      'bornBefore1940' => array(
        'value' => ':true',
        'condition' => '#lessThan(birth_year, 1940)'
      )
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();

function lessThan($record, $columnName, $num)
{
    return $record[$columnName] < $num;
}
?>
     ]]>
     </programlisting>
     This results in the following XML data:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist birth_year="1920" bornBefore1940="true" name="Curtis Mayfield" />
  <artist birth_year="1942" name="Isaac Hayes" />
  <artist birth_year="1930" bornBefore1940="true" name="Ray Charles" />
</favorite_artists>
    ]]>
     </programlisting>
    </para>
    <para>
     In the next example we want a "firstAlbumTitle" attribute for each artist.
     For the purpose of the example we will not use a single left outer join but a complex attribute specification with the "sql" option.
     As retrieving more than one record for a single attribute makes no sense
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.single_record} is always automatically set to true when fetching records
     for attributes.
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'attributes' => array(
      'name',
      'birth_year',
      'firstAlbumTitle' => array(
        'value' => 'title',
        'sql' => array(
          'data' => array(
            'artistid'
          ),
          'query' => "SELECT * FROM album WHERE artist_id = ? ORDER BY published_year"
        )
      )
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     This results in the following XML data:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist birth_year="1920" firstAlbumTitle="Curtis" name="Curtis Mayfield" />
  <artist birth_year="1942" firstAlbumTitle="Shaft" name="Isaac Hayes" />
  <artist birth_year="1930" name="Ray Charles" />
</favorite_artists>
    ]]>
     </programlisting>
     As you can see, the firstAlbumTitle attribute is missing for Ray Charles.
     This is because he does not have any albums in our test database and processing
     the "value" option without any records just makes no sense.
    </para>
    <para>
     In the last example I'd like to demonstrate the use of {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options} within
     a complex attribute specification. As stated before, {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.single_record}
     is always automatically set to true - no matter what you assign to it.
     This time, we want a "firstAlbum" attribute that has a value of "TITLE (GENRE)" - remember that
     "genre" is a colum of the artist table while "title" is a column of the album table.
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'attributes' => array(
      'name',
      'birth_year',
      'firstAlbum' => array(
        'value' => '#combineTitleAndGenre()',
        'sql' => array(
          'data' => array(
            'artistid'
          ),
          'query' => "SELECT * FROM album WHERE artist_id = ? ORDER BY published_year"
        ),
        'sql_options' => array(
          'merge_selective' => array('genre')
        )
      )
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();

function combineTitleAndGenre($record)
{
    return $record['title'] . ' (' . $record['genre'] . ')';
}
?>
     ]]>
     </programlisting>
     This results in the following XML data:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist name="Curtis Mayfield" birth_year="1920" firstAlbum="Curtis (Soul)"/>
  <artist name="Isaac Hayes" birth_year="1942" firstAlbum="Shaft (Soul)"/>
  <artist name="Ray Charles" birth_year="1930"/>
</favorite_artists>
    ]]>
     </programlisting>
    </para>
   </refsect3>
   <refsect3 id="{@id asterisk_shortcut}">
    <title>Using the Asterisk Shortcut</title>
    <para>
     The asterisk shortcut only works with {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications}
     (and {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}).
    </para>
    <para>
     Everything said about
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.asterisk_shortcut Using the Asterisk Shortcut with simple element specifications}
     applies here to!
     The simplest example of using the asterisk shortcut with the attributes option is as follows:
     <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'attributes' => array(
      '*'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    This produces this XML data:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist artistid="1" birth_place="Chicago" birth_year="1920" genre="Soul" name="Curtis Mayfield" />
  <artist artistid="2" birth_place="Tennessee" birth_year="1942" genre="Soul" name="Isaac Hayes" />
  <artist artistid="3" birth_place="Mississippi" birth_year="1930" genre="Country and Soul" name="Ray Charles" />
</favorite_artists>
    ]]>
    </programlisting>
    </para>
   </refsect3>
  </refsect2>

  <refsect2 id="{@id options_rowtag}">
   <title>$options['rowTag']</title>
   <para>
    The name of the tag that encloses each record. The default is 'row'.
   </para>
   <para>
    Here goes an example of 'rowTag' being used at the root level:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'name',
        'birth_year',
        'genre'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    'rowTag' was set to 'artist' therefore the resulting XML data is:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <genre>Soul</genre>
  </artist>
  <artist>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <genre>Soul</genre>
  </artist>
  <artist>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <genre>Country and Soul</genre>
  </artist>
</favorite_artists>
    ]]>
    </programlisting>
   </para>
   <para>
    Now let's have a look at a more advanced example:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    Here 'rowTag' on the root level is set to 'artist' while ['elements']['albums']['rowTag']
    is set to 'album'. This example is taken from {@tutorial XML_Query2XML.pkg#casestudies.case02},
    so please see there for the resulting XML data and further discussion.
   </para>
   <para>
    In some situations, 'rowTag' can be omitted all together:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'name' => array(
            'value' => 'name',
            'attributes' => array(
                'type' => ':full_name'
            )
        ),
        'birth_year',
        'music_genre' => 'genre'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    Here the complex element definition ['elements']['name'] has no 'rowTag' option. This is alright
    because the specification's array key ('name' in this case) is used by default.
   </para>
  </refsect2>

  <refsect2 id="{@id options_dynamicrowtag}">
   <title>$options['dynamicRowTag']</title>
   <para>
    Use this option if you want the name of an XML element determined at run time (e.g. you want to pull the
    XML element name from the database). Note: if this option is present,
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_rowtag} will be ignored.
   </para>
   <para>
    What you can assign to $options['dynamicRowTag'] is very similar as what you can use for
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_value}
    or a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications Simple Element Specification}.

    $options['dynamicRowTag'] can be of the following types:
    <itemizedlist>
     <listitem>
      <emphasis>COLUMN NAME</emphasis>: this is the default if not preceeded by ':' or '#'.
      If the column does not exist, an {@link XML_Query2XML_ConfigException} will be thrown.
     </listitem>
     <listitem>
      <emphasis>STATIC TEXT with a : prefix</emphasis>: if the value is preceeded by a colon (':'), it is
      interpreted as static text.
     </listitem>
     <listitem>
      <emphasis>CALLBACK FUNCTION with a # prefix</emphasis>: if the value is preceeded by a pound sign ('#'), it
       is interpreted as a callback function. You can use a regular function (e.g. '#myFunction()') or a static
       method (e.g. '#MyClass::myFunction()') - for how to use a non-static method, see the type COMMAND OBJECT.
       The current record will be passed to the callback function
       as an associative array. You can also pass additional string arguments to the callback function by specifing
       them within the opening and closing brace; e.g. '#Utils::limit(12)' will result in Util::limit() being
       called with the current record as the first and '12' as the second argument. If you do not want
       to pass additional arguments to the callback function, the opening and closing brace are optional.
       The callback function's return value obviously has to be a string that is a valid XML element name.
     </listitem>
     <listitem>
       <emphasis>COMMAND OBJECT (object)</emphasis>: If you want to use a non-static method as a
       callback function, you can do so by specifying the value as an instance of a class that
       implements the {@link XML_Query2XML_Callback} interface. This implementation of the
       {@link http://en.wikipedia.org/wiki/Command_pattern command pattern} gives you all the
       flexibility. The disadvantage ist that you cannot use the XML UNSERIALIZATION prefix
       or the CONDITIONAL prefix. Note: you have to require_once 'XML/Query2XML/Callback.php'
       before using the XML_Query2XML_Callback interface. The return value of a COMMAND OBJECT's
       execute() method is treated exactly the same as the return value of a CALLBACK FUNCTION.
      </listitem>
    </itemizedlist>
   </para>
   <para>
    Let's have a look at a straightforward example: we want our customer's email addresses inside a tag named
    after the customer's first name, e.g. &lt;John&gt;john.doe@example.com&lt;/John&gt;:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM customer",
  array(
    'rootTag' => 'customers',
    'idColumn' => 'customerid',
    'rowTag' => 'customer',
    'elements' => array(
        'customerid',
        'name_and_email' => array(
            'dynamicRowTag' => 'first_name',
            'value' => 'email'
        )
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
   ]]>
   </programlisting>
   The resulting XML looks like this:
   <programlisting role="tutorial">
   <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<customers>
  <customer>
    <customerid>1</customerid>
    <Jane>jane.doe@example.com</Jane>
  </customer>
  <customer>
    <customerid>2</customerid>
    <John>john.doe@example.com</John>
  </customer>
  <customer>
    <customerid>3</customerid>
    <Susan>susan.green@example.com</Susan>
  </customer>
  <customer>
    <customerid>4</customerid>
    <Victoria>victory.alt@example.com</Victoria>
  </customer>
  <customer>
    <customerid>5</customerid>
    <Will>will.wippy@example.com</Will>
  </customer>
  <customer>
    <customerid>6</customerid>
    <Tim>tim.raw@example.com</Tim>
  </customer>
  <customer>
    <customerid>7</customerid>
    <Nick>nick.fallow@example.com</Nick>
  </customer>
  <customer>
    <customerid>8</customerid>
    <Ed>ed.burton@example.com</Ed>
  </customer>
  <customer>
    <customerid>9</customerid>
    <Jack>jack.woo@example.com</Jack>
  </customer>
  <customer>
    <customerid>10</customerid>
    <Maria>maria.gonzales@example.com</Maria>
  </customer>
</customers>
   ]]>
   </programlisting>

   </para>
  </refsect2>

  <refsect2 id="{@id options_roottag}">
   <title>$options['rootTag']</title>
   <para>
    The name of the root tag that encloses all other tags. On the root level, the default is 'root'.
    On all other levels omitting the rootTag option means that the row tags will not be enclosed by
    a root tag but will directly be placed inside the parent tag.
   </para>
   <para>
    Here goes an example of 'rootTag' being used at the root level:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'name',
        'birth_year',
        'genre'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    'rootTag' was set to 'favorite_artists'. The resulting XML data therefore is:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
<artist>
  <name>Curtis Mayfield</name>
  <birth_year>1920</birth_year>
  <genre>Soul</genre>
</artist>
<artist>
  <name>Isaac Hayes</name>
  <birth_year>1942</birth_year>
  <genre>Soul</genre>
</artist>
<artist>
  <name>Ray Charles</name>
  <birth_year>1930</birth_year>
  <genre>Country and Soul</genre>
</artist>
</favorite_artists>
    ]]>
    </programlisting>
   </para>
   <para>
    Here goes an example with the rootTag being used at a lower level:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    ['elements']['albums']['rootTag'] is set to 'albums'. Therefore all 'album' tags of a single
    artist will be enclosed by a singel 'albums' tag. This example is actually taken from
    {@tutorial XML_Query2XML.pkg#casestudies.case02}, so please see there for the resulting XML data
    and further discussion.
   </para>
   <para>
    As shown in {@tutorial XML_Query2XML.pkg#casestudies.case04} is is also possible to assign
    an empty string to the rootTag option or to omit it at all. In our case this results in
    all the album tags not being surrounded by a single 'albums' tag but being directly placed
    inside the 'artist' tag:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    The resulting XML looks like this:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
    <album>
      <albumid>1</albumid>
      <title>New World Order</title>
      <published_year>1990</published_year>
      <comment>the best ever!</comment>
    </album>
    <album>
      <albumid>2</albumid>
      <title>Curtis</title>
      <published_year>1970</published_year>
      <comment>that man's got somthin' to say</comment>
    </album>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
    <album>
      <albumid>3</albumid>
      <title>Shaft</title>
      <published_year>1972</published_year>
      <comment>he's the man</comment>
    </album>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
  </artist>
</music_library>
    ]]>
    </programlisting>
   <para>
   </para>
    Note however that a hidden child element is used as a container
    to ensure the order of the generated XML elements. Internally all elements with a name
    that starts with '__' are hidden. An explicit definition of the hidden complex element would look
    like this:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'rootTag' => '__albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
   </para>
  </refsect2>

  <refsect2 id="{@id options_value}">
   <title>$options['value']</title>
   <para>
    The value of an XML element's child text node. The specification can be of the following types:
     <itemizedlist>
      <listitem>
       <emphasis>COLUMN NAME</emphasis>: this is the default if not preceeded by ':' or '#'.
       If the column does not exist, an {@link XML_Query2XML_ConfigException} will be thrown.
      </listitem>
      <listitem>
       <emphasis>STATIC TEXT with a : prefix</emphasis>: if the value is preceeded by a colon (':'), it is
       interpreted as static text.
      </listitem>
      <listitem>
       <emphasis>CALLBACK FUNCTION with a # prefix</emphasis>: if the value is preceeded by a pound sign ('#'), it
        is interpreted as a callback function. You can use a regular function (e.g. '#myFunction()') or a static
        method (e.g. '#MyClass::myFunction()') - for how to use a non-static method, see the type COMMAND OBJECT.
        The current record will be passed to the callback function
        as an associative array. You can also pass additional string arguments to the callback function by specifing
        them within the opening and closing brace; e.g. '#Utils::limit(12)' will result in Util::limit() being
        called with the current record as the first and '12' as the second argument. If you do not want
        to pass additional arguments to the callback function, the opening and closing brace are optional.
        The callback function's return value will be converted to a string and used as the child text node
        if it is anything but an object or an array. If you do return an object or an array from a callback
        function it has to be an instance of {@link http://www.php.net/manual/en/ref.dom.php DOMNode} or
        an array of DOMNode instances. Please see {@tutorial XML_Query2XML.pkg#other_xml_data_sources} for examples
        and further details. If an instances of any other class is returned, a XML_Query2XML_XMLException will be thrown.
      </listitem>
      <listitem>
        <emphasis>COMMAND OBJECT (object)</emphasis>: If you want to use a non-static method as a
        callback function, you can do so by specifying the value as an instance of a class that
        implements the {@link XML_Query2XML_Callback} interface. This implementation of the
        {@link http://en.wikipedia.org/wiki/Command_pattern command pattern} gives you all the
        flexibility. The disadvantage ist that you cannot use the XML UNSERIALIZATION prefix
        or the CONDITIONAL prefix. Note: you have to require_once 'XML/Query2XML/Callback.php'
        before using the XML_Query2XML_Callback interface. The return value of a COMMAND OBJECT's
        execute() method is treated exactly the same as the return value of a CALLBACK FUNCTION.
       </listitem>
     </itemizedlist>
     There are four more prefixes available that can be used in conjunction with all the prifixes described above:
     <itemizedlist>
      <listitem>
       <emphasis>XML UNSERIALIZATION prefix &amp;</emphasis>: the ampersand (&amp;) prefix allows you to
       automatically unserialize string data, i.e. transform a string into a
       {@link http://www.php.net/manual/en/ref.dom.php#dom.class.domdocument DOMDocument}. DOMDocument's
       {@link http://www.php.net/manual/en/function.dom-domdocument-loadxml.php loadXML()} method will be
       used for this purpose. You can combine all three types with this prefix: '&amp;COLUMN_NAME',
       '&amp;#function()' or '&amp;:&lt;name&gt;John&lt;/name&gt;' will all work. You can even use the CONDITIONAL prefix
       which has to preceed all other prefixes. If the data cannot be unserialized i.e.
       {@link http://www.php.net/manual/en/function.dom-domdocument-loadxml.php DOMDocument::loadXML()}
       returns false, a XML_Query2XML_XMLException will be thrown. Please see
       {@tutorial XML_Query2XML.pkg#other_xml_data_sources} for examples and further
       details.
      </listitem>
      <listitem>
       <emphasis>BASE64 ENCODING prefix ^</emphasis>: if the specification starts with a carrat sign ('^'),
       the element value will be passed to {@link http://www.php.net/base64_encode base64_encode()}.
       The BASE64 ENCODING prefix can be used with all the prefixes described above (just put the BASE64 ENCODING prefix first):
       e.g. '^#', '^:' or '^COLUMN_NAME'.
      </listitem>
      <listitem>
       <emphasis>CDATA SECTION prefix =</emphasis>: if the specification starts with an equal sign ('='),
       the element value will be enclosed in a CDATA section. A CDATA section starts with
       "&lt;![CDATA[" and ends with "]]&gt;".
       The CDATA SECTION prefix can be used with all the prefixes described above (just put the CDATA SECTION prefix first):
       e.g. '=#', '=:', '=COLUMN_NAME' or '=^'.
      </listitem>
      <listitem>
       <emphasis>CONDITIONAL prefix ?</emphasis>: if the specification starts with a question mark ('?'),
       the whole element will be skipped if the value equals (==) an empty string. The CONDITIONAL prefix
       can be combined with all types described above: if you do this you have to write the CONDITIONAL
       prefix first e.g. '?#', '?:', '?&amp;', '?=', '?^', or '?COLUMN_NAME'.
      </listitem>
     </itemizedlist>
     Note: for ovious reasons, the XML UNSERIALIZATION prefix and the CONDITIONAL prefix cannot be
     combined with a COMMAND OBJECT.
   </para>
   <para>
     Basically, the same syntax can be use for
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications},
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications},
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification} and
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn} because the private method
     {@link XML_Query2XML::_applyColumnStringToRecord()} is used in all cases.
   </para>
   <para>
     The following example demonstrates the usage of some of the types (for a full demonstration of all types
     see the second example under {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}).
     The comment element will be skipped if its value == "".
     Same holds true for the genre element which uses the trim'ed version of the value stored in the genre column. The comment
     tag has an attribute named type with a static value of "short text". The published_century element gets the century
     calculated using floor and has the attribute digitCount with a static value of 2.
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT
    *
   FROM
    album al,
    artist ar
   WHERE
    al.artist_id = ar.artistid",
  array(
    'rootTag' => 'albums',
    'idColumn' => 'albumid',
    'rowTag' => 'album',
    'elements' => array(
        'albumid',
        'title',
        'published_year',
        'published_century' => array(
            'value' => "#Utils::getPublishedYearCentury()",
            'attributes' => array(
                'digitCount' => ':2'
            )
        ),
        'comment' => array(
            'value' => '?comment',
            'attributes' => array(
                'type' => ':short text'
            )
        ),
        'genre' => array(
            'value' => "?#Utils::trimGenre()"
        )
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();

class Utils
{
    function trimGenre($record)
    {
        return trim($record['genre']);
    }

    function getPublishedYearCentury($record)
    {
        return floor($record['published_year']/100);
    }
}
?>
     ]]>
     </programlisting>
     The resulting XML data looks like this:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<albums>
  <album>
    <albumid>1</albumid>
    <title>New World Order</title>
    <published_year>1990</published_year>
    <published_century digitCount="2">19</published_century>
    <comment type="short text">the best ever!</comment>
    <genre>Soul</genre>
  </album>
  <album>
    <albumid>2</albumid>
    <title>Curtis</title>
    <published_year>1970</published_year>
    <published_century digitCount="2">19</published_century>
    <comment type="short text">that man's got somthin' to say</comment>
    <genre>Soul</genre>
  </album>
  <album>
    <albumid>3</albumid>
    <title>Shaft</title>
    <published_year>1972</published_year>
    <published_century digitCount="2">19</published_century>
    <comment type="short text">he's the man</comment>
    <genre>Soul</genre>
  </album>
</albums>
     ]]>
     </programlisting>
   </para>
  </refsect2>

  <refsect2 id="{@id options_condition}">
   <title>$options['condition']</title>
   <para>
    This option allows you to specify a condition for the element to be included.
    The string assigned to the condition option can be of the following types:
      <itemizedlist>
       <listitem>
        <emphasis>COLUMN NAME</emphasis>: this is the default if not preceeded by ':' or '#'.
        If the column does not exist, an {@link XML_Query2XML_ConfigException} will be thrown.
        Remember that the string '0' or '' will both evaluate to false which
        means that the element would be skipped. Note: in most cases you will be much
        better off changing your WHERE clause than using this type of condition.
       </listitem>
       <listitem>
        <emphasis>STATIC TEXT with a : prefix</emphasis>: if the value is preceeded by a colon (':'), it is
        interpreted as static text. Remember that the string '0' or '' will both evaluate to false which
        means that the element would be skipped.
       </listitem>
       <listitem>
        <emphasis>CALLBACK FUNCTION with a # prefix</emphasis>: if the value is preceeded by a pound sign ('#'), it
        is interpreted as a callback function. You can use a regular function (e.g. '#myFunction()') or a static
        method (e.g. '#MyClass::myFunction()') - for how to use a non-static method, see the type COMMAND OBJECT.
        The current record will be passed to the callback function
        as an associative array. You can also pass additional string arguments to the callback function by specifing
        them within the opening and closing brace; e.g. '#Utils::limit(12)' will result in Util::limit() being
        called with the current record as the first and '12' as the second argument. If you do not want
        to pass additional arguments to the callback function, the opening and closing brace are optional.
       </listitem>
       <listitem>
        <emphasis>COMMAND OBJECT (object)</emphasis>: If you want to use a non-static method as a
        callback function, you can do so by specifying the value as an instance of a class that
        implements the {@link XML_Query2XML_Callback} interface. This implementation of the
        {@link http://en.wikipedia.org/wiki/Command_pattern command pattern} gives you all the
        flexibility. Note: you have to require_once 'XML/Query2XML/Callback.php'
        before using the XML_Query2XML_Callback interface. The return value of a COMMAND OBJECT's
        execute() method is treated exactly the same as the return value of a CALLBACK FUNCTION.
       </listitem>
      </itemizedlist>

    This option provides a similar function as the "?" prefix for column specifications - see
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications},
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications} and {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_value}.
    The difference is that $options['condition'] is more powerful: you can call any external function you like
    to determin whether the element shall be included.
    Here goes a little example:
    <programlisting role="php">
    <![CDATA[
<?php
if (isset($_REQUEST['includeCondition'])) {
    $includeCondition = ($_REQUEST['includeCondition'] == '1');
} else {
    $includeCondition = false;
}
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom =& $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'condition' => '#isSpecialPublishedYear()',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment' => array(
                        'value' => 'comment',
                        'condition' => ':' . ($includeCondition ? '1' : '0')
                    )
                )
            )
        )
    )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();

/**Returns whether $year is 1970 or 1972.
*/
function isSpecialPublishedYear($record)
{
    //do some highly complex calculations ...
    return $record['published_year'] == 1970 || $record['published_year'] == 1972;
}
?>
    ]]>
    </programlisting>
    The resulting XML data is:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>2</albumid>
        <title>Curtis</title>
        <published_year>1970</published_year>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>3</albumid>
        <title>Shaft</title>
        <published_year>1972</published_year>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
    <albums />
  </artist>
</music_library>
    ]]>
    </programlisting>
   </para>
   <para>
    Note that (if present) {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql} will
    get processed *before* evaluating the condition. This allows you to wirte code
    like the following:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT
    *
   FROM
    artist",
  array(
    'rootTag' => 'artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'artistid',
        'name',
        'albums' => array(
            'idColumn' => 'albumid',
            'sql' => array(
                'data' => array(
                    'artistid'
                ),
                'query' => "SELECT * FROM album WHERE artist_id = ?",
            ),
            'condition' => '#isGT1980()',
            'elements' => array(
                'title',
                'published_year'
            )
        )
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();

function isGT1980($record)
{
    return $record['published_year'] > 1980;
}
?>
    ]]>
    </programlisting>
    "published_year" is a column of the table album but as the "sql" option is processed before evaluating
    the "condition" option everything works just fine:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<artists>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <albums>
      <title>New World Order</title>
      <published_year>1990</published_year>
    </albums>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
  </artist>
</artists>
    ]]>
    </programlisting>
   </para>
  </refsect2>

  <refsect2 id="{@id options_sql}">
   <title>$options['sql']</title>
   <para>
    <emphasis>Note:</emphasis> This option is driver-specific. The following discussion is limited
    to the database-related drivers.
   </para>
   <para>
    This and {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options} are the only options
    that can only be present within
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}.
    If given at the root level, it would be just ignored. $options['sql'] allows you to split
    up one huge JOIN into multiple smaller queries. You might want (or have) to do this in
    several scenarios:
    <itemizedlist>
     <listitem>
      Your RDBMS has a maximum number of fields it can return in a single query and you've reached it.
     </listitem>
     <listitem>
      You are short on memory: let's say your big JOIN returns 100 fields and you have 10 000 records.
      It might turn out that the memory consumption is lower if you split up the single big JOIN into
      multiple quieres that have smaller result sets. As all the data won't be in memory at once,
      it might even run faster.
     </listitem>
     <listitem>
      You are too lazy to think about how to best join these 8 tables :)
     </listitem>
    </itemizedlist>
    You will definitively want to do some {@tutorial XML_Query2XML.pkg#profiling} before deciding whether
    or not to split up one big JOIN into multiple smaller JOINs.
   </para>
   <para>
    There are two ways of specifying $options['sql']:
    <itemizedlist>
     <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.simplequeryspecification}: uses the query() method provided by the database abstraction layer (PDO/MDB2/DB/ADOdb) - use it with care
     </listitem>
     <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification}: uses
      the prepare() and execute() methods provided by the database abstraction layer and
      can therefore prevent SQL injection and is also faster in most scenarios
     </listitem>
    </itemizedlist>
   </para>
   <refsect3 id="{@id simplequeryspecification}">
    <title>Simple Query Specification</title>
    <para>
     Since v0.8.0 a simple query specifications are purely static strings (in most cases
     you will want to use a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification}):
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
     WHERE
        artistid = 1",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'sql' => 'SELECT * FROM album WHERE artist_id = 1',
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
    </programlisting>
    </para>
    <para>
     To understand how $options['sql'] really works, some knowledge of XML_Query2XML's internals might be helpful:
     {@link XML_Query2XML::getXML()} calls the private method {@link XML_Query2XML::_getNestedXMLRecord()} for
     every record retrieved from the database using the SQL statement passed to getXML() as first
     argument. XML_Query2XML::_getNestedXMLRecord() will then process the current record according
     to the settings specified in $options. The processing of all
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}
     is handed off to the private method {@link XML_Query2XML::_processComplexElementSpecification()}.
     XML_Query2XML::_processComplexElementSpecification() in turn will call the private method
     {@link XML_Query2XML::_applySqlOptionsToRecord()} to interpret $options['sql'] and {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options}.
     XML_Query2XML::_processComplexElementSpecification() will then call again {@link XML_Query2XML::_getNestedXMLRecord()} for
     every record retrieved using the query specified in the 'sql' option.
    </para>
   </refsect3>
   <refsect3 id="{@id complexqueryspecification}">
    <title>Complex Query Specification</title>
    <para>
    A Complex Query Specification uses the database abstraction layer's prepare() and execute() methods
    and therefore prevents SQL injection and is also faster
    than a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.simplequeryspecification} in most scenarios.
    It can consist of multiple parts (only $options['sql']['query'] is mandatory):
    <itemizedlist>
     <listitem>
      <emphasis>$options['sql']['query']</emphasis>: the SQL query as a string that contains a placeholder
      for each element of $options['sql']['data'].
     </listitem>
     <listitem>
      <emphasis>$options['sql']['driver']</emphasis>: allows you to use a different XML_Query2XML_Driver
      for this complex query than the one passed to
      {@tutorial XML_Query2XML.pkg#query2xml_factory}. Please see
      {@tutorial XML_Query2XML.pkg#multipledrivers} for details. $options['sql']['driver'] is optional.
     </listitem>
     <listitem>
      <emphasis>$options['sql']['limit']</emphasis>: allows you to limit the number of records returned from the
      query. It has to be a numeric value. Please note that a value of 0 (or '0') is equivalent to not
      setting $options['sql']['limit'] at all. $options['sql']['limit'] and $options['sql']['offset'] are
      only interpreted by the drivers for PEAR MDB2 and PEAR DB. All other drivers simply ignore these two
      options.
     </listitem>
     <listitem>
      <emphasis>$options['sql']['offset']</emphasis>: allows you to set the number of the first record
      to retrieve. This has to be a numeric value. The default is 0. Please note that this option will
      be ignored unless $options['sql']['limit'] is set. $options['sql']['offset'] and
      $options['sql']['limit'] are only interpreted by the drivers for PEAR MDB2 and PEAR DB.
      All other drivers simply ignore these two options.
     </listitem>
     <listitem>
      <emphasis>$options['sql']['data']</emphasis>: an indexed array of values. This is optional.
      The specification can be of the following types:
      <itemizedlist>
       <listitem>
        <emphasis>COLUMN NAME</emphasis>: this is the default if not preceeded by ':' or '#'.
        If the column does not exist, an {@link XML_Query2XML_ConfigException} will be thrown. Note
        that the parent record will be used! This is quite logic as this SQL statement has not been executed yet :)
       </listitem>
       <listitem>
        <emphasis>STATIC TEXT with a : prefix</emphasis>: if the value is preceeded by a colon (':'), it is
        interpreted as static text.
       </listitem>
       <listitem>
        <emphasis>CALLBACK FUNCTION with a # prefix</emphasis>: if the value is preceeded by a pound sign ('#'), it
        is interpreted as a callback function. You can use a regular function (e.g. '#myFunction()') or a static
        method (e.g. '#MyClass::myFunction()') - for how to use a non-static method, see the type COMMAND OBJECT.
        The current record will be passed to the callback function
        as an associative array. You can also pass additional string arguments to the callback function by specifing
        them within the opening and closing brace; e.g. '#Utils::limit(12)' will result in Util::limit() being
        called with the current record as the first and '12' as the second argument. If you do not want
        to pass additional arguments to the callback function, the opening and closing brace are optional.
       </listitem>
       <listitem>
        <emphasis>COMMAND OBJECT (object)</emphasis>: If you want to use a non-static method as a
        callback function, you can do so by specifying the value as an instance of a class that
        implements the {@link XML_Query2XML_Callback} interface. This implementation of the
        {@link http://en.wikipedia.org/wiki/Command_pattern command pattern} gives you all the
        flexibility. Note: you have to require_once 'XML/Query2XML/Callback.php'
        before using the XML_Query2XML_Callback interface. The return value of a COMMAND OBJECT's
        execute() method is treated exactly the same as the return value of a CALLBACK FUNCTION.
       </listitem>
      </itemizedlist>
      The same syntax (with the additional '?' prefix) can be use for
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications},
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_value},
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications} and
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn} because the private method
      {@link XML_Query2XML::_applyColumnStringToRecord()} is used in all cases.
      <emphasis>Note:</emphasis> $options['sql']['data'] is optional!
     </listitem>
    </itemizedlist>
    Here is a simple example similar to {@tutorial XML_Query2XML.pkg#casestudies.case03}:
    </para>
    <para>
     <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => "SELECT * FROM album WHERE artist_id = ?"
                ),
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
    </programlisting>
    </para>
   </refsect3>
  </refsect2>

  <refsect2 id="{@id options_sql_options}">
   <title>$options['sql_options']</title>
   <para>
    This allows you to specify how {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql} is
    handled. $options['sql_options'] is an associative array that can have the following fileds:
    <itemizedlist>
     <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.cached}
     </listitem>
     <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.single_record}
     </listitem>
     <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.merge}
     </listitem>
     <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.merge_selective}
     </listitem>
     <listitem>
      {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.merge_master}
     </listitem>
    </itemizedlist>
    Per default all options are set to the boolean value false.
   </para>
   <refsect3 id="{@id cached}">
    <title>$options['sql_options']['cached']</title>
    <para>
     Since 1.5.0RC1 Caching is deactivated by default.
     If caching is activated the result of a query is stored in the private associative array
     {@link XML_Query2XML::$_recordCache} using the SQL query string as key. If the exact same
     query needs to be executed a second time, its results can be retrieved from cache.
    </para>
    <para>
     Before setting $options['sql_options']['cached'] to true, do some
     {@tutorial XML_Query2XML.pkg#profiling}. As documented in
     {@tutorial XML_Query2XML.pkg#profiling.getprofile} the CACHED column in the profile output will
     show 'true!' if caching is performed without being necessary.
    </para>
    <para>
     Caching only makes sense, if you have to run exactly the same query multiple times.
    </para>
   </refsect3>
   <refsect3 id="{@id single_record}">
    <title>$options['sql_options']['single_record']</title>
    <para>
     Use this option to make sure that the SQL query you specified in
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql} returns only a single record.
     This option is in fact of limited use. Do not use it to fetch only the first record
     from a large result set. (SQL is your friend: use a better WHERE clause!)
    </para>
   </refsect3>
   <refsect3 id="{@id merge}">
    <title>$options['sql_options']['merge']</title>
    <para>
     By default no merging is done so that less memory is used. This means that the data of the record
     present on the parent level will not be available at this level. Only the data returned by
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql} will be available (and therefore
     use up memory). If you also need the data of the record present on the parent level the two arrays
     have to be merged using {@link http://www.php.net/array_merge array_merge()}. If
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql} returned multiple records, each of them
     has to be merged with the one of the parent level separatly:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'MUSIC_LIBRARY',
        'rowTag' => 'ARTIST',
        'idColumn' => 'artistid',
        'elements' => array(
            'NAME' => 'name',
            'BIRTH_YEAR' => 'birth_year',
            'GENRE' => 'genre',
            'albums' => array(
                'sql' => array(
                    'data' => array('artistid'),
                    'query' => "SELECT * FROM album WHERE artist_id = ?"
                ),
                'sql_options' => array(
                    'merge' => true
                ),
                'rootTag' => '',
                'rowTag' => 'ALBUM',
                'idColumn' => 'albumid',
                'elements' => array(
                    'TITLE' => 'title',
                    'PUBLISHED_YEAR' => 'published_year',
                    'COMMENT' => 'comment',
                    'GENRE' => 'genre'
                )
            )
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     This produces quite some overhead. It is therefore highly recommended to use
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.merge_selective}
     described in the next section.
    </para>
   </refsect3>
   <refsect3 id="{@id merge_selective}">
    <title>$options['sql_options']['merge_selective']</title>
    <para>
     As a full merge with the parent record might severly affect the performance, the sql option
     merge_selective allows you to only merge the current record with specific columns of the
     parent record. Just place the names of all columns of the parent record you want to be
     available in the current record in an array and assign it to the merge_selective option.
     Here goes an example:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'MUSIC_LIBRARY',
        'rowTag' => 'ARTIST',
        'idColumn' => 'artistid',
        'elements' => array(
            'NAME' => 'name',
            'BIRTH_YEAR' => 'birth_year',
            'GENRE' => 'genre',
            'albums' => array(
                'sql' => array(
                    'data' => array('artistid'),
                    'query' => "SELECT * FROM album WHERE artist_id = ?"
                ),
                'sql_options' => array(
                    'merge_selective' => array('genre')
                ),
                'rootTag' => '',
                'rowTag' => 'ALBUM',
                'idColumn' => 'albumid',
                'elements' => array(
                    'TITLE' => 'title',
                    'PUBLISHED_YEAR' => 'published_year',
                    'COMMENT' => 'comment',
                    'GENRE' => 'genre'
                )
            )
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     Please see {@tutorial XML_Query2XML.pkg#casestudies.case04} for a similar example and
     more discussion of {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.merge_selective}.
    </para>
   </refsect3>
   <refsect3 id="{@id merge_master}">
    <title>$options['sql_options']['merge_master']</title>
    <para>
     If (selective) merging is performed, it might become important which record overwrites the data of the other.
     As soon as both result sets have a column with the same name, there is a confilict that has to
     be resolved. By default, the record of the parent level is the master and overwrites the
     record(s) returned by {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}. If you want
     the new records to overwrite the record of the parent level, set
     $options['sql_options']['merge_master'] to true. Note that this option only has an effect if
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.merge} is set to true or
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.merge_selective} is used.
    </para>
   </refsect3>
  </refsect2>

  <refsect2 id="{@id options_mapper}">
   <title>$options['mapper']</title>
   <para>
    This option allows you to specifiy a function for mapping SQL identifiers to XML names.
    Whenever you use a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications Simple Element Specification}
    or a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications Simple Attribute Specification}
    only with a column name and without a tag/attribute name, the specified column name will be used for the
    tag/attribute name. Please note that mapping is also performed when the
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.asterisk_shortcut} is used.
    Per default $options['mapper'] is set to false which means that no special mapping is used.
    $options['mapper'] can have one of the following formats:
    <itemizedlist>
      <listitem>
       <emphasis>'CLASS::STATIC_METHOD'</emphasis>: this syntax allows you to use a static method
       for mapping:
       <programlisting role="php">
       <![CDATA[
'mapper' => 'MyMapper::map'
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>array('CLASS', 'STATIC_METHOD')</emphasis>: this syntax also allows you to use a static
       method for mapping:
       <programlisting role="php">
       <![CDATA[
'mapper' => array('MyMapper', 'map')
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>array($instance, 'METHOD')</emphasis>: this syntax allows you to use a non-static
       method for mapping:
       <programlisting role="php">
       <![CDATA[
'mapper' => array($myMap, 'map')
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>'FUNCTION'</emphasis>: this syntax allows you to use a regular function
       for mapping:
       <programlisting role="php">
       <![CDATA[
'mapper' => 'myUppercaseMapper'
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>false</emphasis>: use the boolean value false (or any other value that == false) to
       deactivate any special mapping:
       <programlisting role="php">
       <![CDATA[
'mapper' => false
       ]]>
       </programlisting>
      </listitem>
    </itemizedlist>
    Remember that the mapping only applies to
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}
    and {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications}
    that do not explicitly have a tag/attribute name or those that have a tag/attribute name that contains
    an {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.asterisk_shortcut asterisk shortcut}.
    The following example will also show that a mapper defined at the root level is also used at all lower levels
    (unless it gets overwritten, see
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_mapper.multiple_mappers}):
    <programlisting role="php">
     <![CDATA[
<?php
class SomeMapper
{
    public function map($str)
    {
        //do something with $str
        return $str;
    }
}

require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/ISO9075Mapper.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(           //
  "SELECT * FROM artist",            //
  array(                             //
    'rootTag' => 'favorite_artists', //no mapping
    'idColumn' => 'artistid',        //nothing to map
    'rowTag' => 'artist',            //no mapping
    'mapper' => 'SomeMapper::map',   //
    'elements' => array(             //
      'artistid',                 //mapping
      'NAME' => 'name',           //no mapping as the tag name is specified
      '*',                        //mapping
      'TAG_*' => '*',             //does a mapping too!
      'albums' => array(          //nothing to map
        'sql' => array(           //
          'data' => array(        //
            'artistid'            //nothing to map
          ),                      //
          'query' => 'SELECT * FROM album WHERE artist_id = ?'      //
        ),                      //
        'rootTag' => 'albums',  //no mapping
        'rowTag' => 'album',    //no mapping
        'idColumn' => 'albumid',//nothing to map
        'elements' => array(    //
          'albumid',          //mapping using the mapper specified at the root level
          'title',            //mapping using the mapper specified at the root level
          'published_year',   //mapping using the mapper specified at the root level
          'comment'           //mapping using the mapper specified at the root level
        )                     //
      )                       //
    ),                        //
    'attributes' => array(        //
      'artistid',                 //mapping
      'NAME' => 'name',           //no mapping as the tag name is specified
      '*',                        //mapping
      'TAG_*' => '*'              //does a mapping too!
    )                             //
  )                               //
);                                //
header('Content-Type: application/xml');    //
print $dom->saveXML();                      //
?>
     ]]>
     </programlisting>

   </para>

   <refsect3 id="{@id 9075mapping}">
    <title>Mapping SQL identifiers to XML names in accordance with ISO/IEC 9075-14:2005</title>
    <para>
     The package XML_Query2XML also implements the Final Committee Draft for ISO/IEC 9075-14:2005,
     section "9.1 Mapping SQL &lt;identifier&gt;s to XML Names". ISO/IEC 9075-14:2005 is available
     online at {@link http://www.sqlx.org/SQL-XML-documents/5FCD-14-XML-2004-07.pdf}.
    </para>
    <para>
     A lot of characters are legal in SQL identifiers but cannot be used within
     XML names. To begin with, SQL identifiers can contain any Unicode character
     while XML names are limited to a certain set of characters. E.g the
     SQL identifier "&lt;21yrs in age" obviously is not a valid XML name.
     '#', '{', and '}' are also not allowed. Fully escaped SQL identifiers
     also must not contain a column (':') or start with "xml" (in any case
     combination). Illegal characters are mapped to a string of the form
     _xUUUU_ where UUUU is the Unicode value of the character.
    </para>
    <para>
     The following is a table of example mappings:
     <![CDATA[
+----------------+------------------------+------------------------------------+
| SQL-Identifier | Fully escaped XML name | Comment                            |
+----------------+------------------------+------------------------------------+
| dept:id        | dept_x003A_id          | ":" is illegal                     |
| xml_name       | _x0078_ml_name         | must not start with [Xx][Mm][Ll]   |
| XML_name       | _x0058_ML_name         | must not start with [Xx][Mm][Ll]   |
| hire date      | hire_x0020_date        | space is illegal too               |
| Works@home     | Works_x0040_home       | "@" is illegal                     |
| file_xls       | file_x005F_xls         | "_" gets mapped if followed by "x" |
| FIRST_NAME     | FIRST_NAME             | no problem here                    |
+----------------+------------------------+------------------------------------+
     ]]>
    </para>
    <para>
     The ISO 9075-mapping does produce some overhead which might not be needed in
     a lot of situations. Therefore it is not the default mapper. In most cases
     it will be sufficient to validate your XML schema once using tools like the free
     {@link http://www.altova.com/download_spy_home.html XMLSpy Home Edition}.
    </para>
    <para>
     To use the ISO 9075-mapper that comes with XML_Query2XML you have to:
     <itemizedlist>
      <listitem>
       make sure that {@link http://pear.php.net/package/I18N_UnicodeString PEAR I18N_UnicodeString}
       is installed - see {@tutorial XML_Query2XML.pkg#requirements}.
      </listitem>
      <listitem>
       require XML/Query2XML/ISO9075Mapper.php
      </listitem>
      <listitem>
       set the option "mapper" to "XML_Query2XML_ISO9075Mapper::map"
      </listitem>
     </itemizedlist>
     Here goes an example:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/ISO9075Mapper.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'mapper' => 'XML_Query2XML_ISO9075Mapper::map',
    'elements' => array(
        '*'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
    </para>
   </refsect3>
   <refsect3 id="{@id own_mappers}">
    <title>Building your own mappers</title>
    <para>
     There are cases when you will want the tag and attribute names to be somehow different from
     the column names. Let's say you want to use the column names as tag and attribute names
     but make them all uppercase. Certainly you could write code like this:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/ISO9075Mapper.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'NAME' => 'name',
        'BIRTH_YEAR' => 'birth_year',
        'BIRTH_PLACE' => 'birth_place',
        'GENRE' => 'genre',
    ),
    'attributes' => array(
        'ARTISTID' => 'artistid'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     But that seems a little redundant, doesn't it? In cases like these it is recommended
     to write your own mapper. As we want to write OO code we don't implement our mapper
     as a function but as a static public method of the new class UppercaseMapper. The
     mapper must take a string as an argument and must return a string:
     <programlisting role="php">
     <![CDATA[
<?php
class UppercaseMapper
{
    public function map($str)
    {
        return strtoupper($str);
    }
}

require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'mapper' => 'UppercaseMapper::map',
    'elements' => array(
        'name',
        'birth_year',
        'birth_place',
        'genre',
    ),
    'attributes' => array(
        'artistid'
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     The resulting XML data looks like this:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<favorite_artists>
  <artist ARTISTID="1">
    <NAME>Curtis Mayfield</NAME>
    <BIRTH_YEAR>1920</BIRTH_YEAR>
    <BIRTH_PLACE>Chicago</BIRTH_PLACE>
    <GENRE>Soul</GENRE>
  </artist>
  <artist ARTISTID="2">
    <NAME>Isaac Hayes</NAME>
    <BIRTH_YEAR>1942</BIRTH_YEAR>
    <BIRTH_PLACE>Tennessee</BIRTH_PLACE>
    <GENRE>Soul</GENRE>
  </artist>
  <artist ARTISTID="3">
    <NAME>Ray Charles</NAME>
    <BIRTH_YEAR>1930</BIRTH_YEAR>
    <BIRTH_PLACE>Mississippi</BIRTH_PLACE>
    <GENRE>Country and Soul</GENRE>
  </artist>
</favorite_artists>
     ]]>
     </programlisting>
    </para>
   </refsect3>
   <refsect3 id="{@id multiple_mappers}">
    <title>Using multiple mappers</title>
    <para>
     Let's say we want to force all tags corresponding to columns of the artist table to be uppercase
     and all tags corresponding to columns of the album table to be lowercase. This can be done
     using two mappers:
     <programlisting role="php">
     <![CDATA[
<?php
class MyMappers
{
    public function uppercaseMapper($str)
    {
        return strtoupper($str);
    }

    public function lowercaseMapper($str)
    {
        return strtolower($str);
    }
}

require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'mapper' => 'MyMappers::uppercaseMapper',
        'elements' => array(
            '*',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'mapper' => 'MyMappers::lowercaseMapper',
                'elements' => array(
                    '*',
                    'artist_id' => '?:'
                )
            )
        )
    )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     As we know that the columns of the album table already are lowercase we could as well
     use one mapper and just deactivate that for the complex element "albums':
     <programlisting role="php">
     <![CDATA[
<?php
class MyMappers
{
    public function uppercaseMapper($str)
    {
        return strtoupper($str);
    }
}

require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'mapper' => 'MyMappers::uppercaseMapper',
        'elements' => array(
            '*',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'mapper' => false,
                'elements' => array(
                    '*',
                    'artist_id' => '?:'
                )
            )
        )
    )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     In both cases the resulting XML data will look like this:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <ARTISTID>1</ARTISTID>
    <NAME>Curtis Mayfield</NAME>
    <BIRTH_YEAR>1920</BIRTH_YEAR>
    <BIRTH_PLACE>Chicago</BIRTH_PLACE>
    <GENRE>Soul</GENRE>
    <albums>
      <album>
        <albumid>1</albumid>
        <title>New World Order</title>
        <published_year>1990</published_year>
        <comment>the best ever!</comment>
      </album>
      <album>
        <albumid>2</albumid>
        <title>Curtis</title>
        <published_year>1970</published_year>
        <comment>that man's got somthin' to say</comment>
      </album>
    </albums>
  </artist>
  <artist>
    <ARTISTID>2</ARTISTID>
    <NAME>Isaac Hayes</NAME>
    <BIRTH_YEAR>1942</BIRTH_YEAR>
    <BIRTH_PLACE>Tennessee</BIRTH_PLACE>
    <GENRE>Soul</GENRE>
    <albums>
      <album>
        <albumid>3</albumid>
        <title>Shaft</title>
        <published_year>1972</published_year>
        <comment>he's the man</comment>
      </album>
    </albums>
  </artist>
  <artist>
    <ARTISTID>3</ARTISTID>
    <NAME>Ray Charles</NAME>
    <BIRTH_YEAR>1930</BIRTH_YEAR>
    <BIRTH_PLACE>Mississippi</BIRTH_PLACE>
    <GENRE>Country and Soul</GENRE>
    <albums />
  </artist>
</music_library>
     ]]>
     </programlisting>
    </para>
   </refsect3>
  </refsect2>

  <refsect2 id="{@id options_encoder}">
   <title>$options['encoder']</title>
   <para>
    This option allows you to specifiy a function/method that performs the
    XML encoding for node and attribute values. Per default it is assumed
    that all data is in ISO-8859-1 (Latin-1) and will be encoded to UTF-8 using
    {@link http://at.php.net/mb_convert_encoding mb_convert_encoding()} or if not available
    using {@link http://at.php.net/utf8_encode utf8_encode()}.
   </para>
   <para>
    For some introduction to XML encoding please see
    {@link http://www.w3schools.com/xml/xml_encoding.asp} and
    {@link http://www.opentag.com/xfaq_enc.htm}.
    Note: I highly recommend to use UTF-8 for XML if you don't have a compelling reason
    to use an other encoding standard.
   </para>
   <para>
    The default encoding mechanism (ISO-8859-1 to UTF-8) will be just fine in most cases
    but sometimes your data might already be in in UTF-8 or you might not want
    your XML to be UTF-8 encoded at all.
   </para>
   <para>
    Please see {@tutorial XML_Query2XML.pkg#encoding} for how to change the encoding
    standard used in the XML declaration.
   </para>
   <para>
    $options['encoder'] can have one of the following formats:
    <itemizedlist>
      <listitem>
       <emphasis>'CLASS::STATIC_METHOD'</emphasis>: this syntax allows you to use a static method
       for encoding:
       <programlisting role="php">
       <![CDATA[
'encoder' => 'MyEncoder::encode'
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>array('CLASS', 'STATIC_METHOD')</emphasis>: this syntax also allows you to use a static
       method for encoding:
       <programlisting role="php">
       <![CDATA[
'encoder' => array('MyEncoder', 'encode')
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>array($instance, 'METHOD')</emphasis>: this syntax allows you to use a non-static
       method for encoding:
       <programlisting role="php">
       <![CDATA[
'encoder' => array($myEncoder, 'encode')
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>'FUNCTION'</emphasis>: this syntax allows you to use a regular function
       for encoding:
       <programlisting role="php">
       <![CDATA[
'encoder' => 'myUTF8toISO88591Encoder'
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>false</emphasis>: use the boolean value false to deactivate encoding:
       <programlisting role="php">
       <![CDATA[
'encoder' => false
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>null</emphasis>: use NULL to reset encoding to the built-in default encoding.
       This default assumes that all data is in ISO-8859-1 (Latin-1) and will encode it to
       UTF-8 using {@link http://at.php.net/mb_convert_encoding mb_convert_encoding()}
       or if not available using {@link http://at.php.net/utf8_encode utf8_encode()}.
       <programlisting role="php">
       <![CDATA[
'encoder' => null
       ]]>
       </programlisting>
      </listitem>
    </itemizedlist>
    One thing you should keep in mind when writing your own encoding (wrapper) functions is
    that the encoder will only be called if the current record has a string value for
    that column; i.e. the encoder will not be called if the column value is NULL.
   </para>
   <para>
    The following example will show that an encoder defined at the root level is also used
    at all lower levels (unless it gets overwritten, see
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_encoder.multiple_encoders}):
    <programlisting role="php">
    <![CDATA[
<?php
class SomeEncoder
{
    public function encode($str)
    {
        //do something with $str
        return $str;
    }
}

require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/ISO9075Mapper.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'encoder' => 'SomeEncoder::encode',     /* we define an encoder at the root level */
    'elements' => array(
      'artistid',                           // encoding will be
      'name',                               // performed on these
      'albums' => array(
        'sql' => array(
          'data' => array(
            'artistid'
          ),
          'query' => 'SELECT * FROM album WHERE artist_id = ?'
        ),
        'rootTag' => 'albums',
        'rowTag' => 'album',
        'idColumn' => 'albumid',
        'elements' => array(
          'albumid',            // encoder setting is affective on all lower
          'title'               // levels
        ),
        'attributes' => array(
          'comment'             // note: encoding is also performed for attributes
        )
      )
    )
  )
);
header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
    </para>
    <refsect3 id="{@id iso88591toutf8}">
     <title>ISO-8859-1 to UTF-8 encoding (default)</title>
     <para>
      This is what will automatically be performed if you do not use $options['encoder']
      at all. This is because most databases use ISO-8859-1 (aka Latin-1) by default.
      As previously stated, XML_Query2XML will use
      {@link http://at.php.net/mb_convert_encoding mb_convert_encoding()}
      or if that is not available {@link http://at.php.net/utf8_encode utf8_encode()} for the
      actual encoding.
     </para>
     <para>
      If you have set $options['encoder'] on the root level but wish to switch back to
      the default on a lower level all you have to do is to use the NULL value:
      <programlisting role="php">
      <![CDATA[
'encoder' => null
      ]]>
      </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id utf8toiso88591}">
     <title>UTF-8 to ISO-8859-1 encoding</title>
     <para>
      If your data is in UTF-8 but you would like your XML to be in ISO-8859-1 (Latin-1),
      you can use {@link http://at.php.net/utf8_decode utf8_decode()}:
      <programlisting role="php">
      <![CDATA[
'encoder' => 'utf8_decode'
      ]]>
      </programlisting>
      or define a wrapper for {@link http://at.php.net/mb_convert_encoding mb_convert_encoding()}
      and use that:
      <programlisting role="php">
      <![CDATA[
function utf8ToLatin1($str)
{
    //hint: mb_convert_encoding (str, to_encoding, from_encoding)
    return mb_convert_encoding($str, 'iso-8859-1', 'UTF-8');
}
      ]]>
      </programlisting>
      specified as encoder:
      <programlisting role="php">
      <![CDATA[
'encoder' => 'utf8ToLatin1'
      ]]>
      </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id disabling}">
     <title>Disabling encoding</title>
     <para>
      If you data already is in the character set you wish to use for the XML, all you
      have to do is to disable the encoding by using a boolean value of false:
      <programlisting role="php">
      <![CDATA[
'encoder' => false
      ]]>
      </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id multiple_encoders}">
     <title>Using multiple encoders</title>
     <para>
      It might happen to you that some of your data sources are in one character set
      while others are in another. This means that you need different encoding procedures
      to convert them all to the same character set you wish to use for the XML (usually UTF-8).
     </para>
     <para>
      In the first example we will assume that all columns of the table artist are in
      ISO-8859-1 (Latin-1) while all columns of the table album are in UTF-8.
      <programlisting role="php">
      <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(    // all columns of the table artist are in
            'artistid',         // ISO-8859-1; the default conversion therefore
            'name',             // is just fine
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'encoder' => false,     // the columns of the album table already are in UTF-8;
                'elements' => array(    // we therefore have to disable encoding
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>

     </para>
     <para>
      For our second example, let's assume that the following columns use the following
      character sets:
      <![CDATA[
+----------------------------------------+
| Column         | Character Set         |
+----------------------------------------+
| artist.name    | ISO-8859-1 (Latin-1)  |
| artist.genre   | UTF-8                 |
| album.title    | UTF-16                |
| album.comment  | Windows-1252          |
+----------------+-----------------------+
      ]]>
      As our XML output shall be in UTF-8 we have to use multiple encoders on a
      per-column basis:
      <programlisting role="php">
      <![CDATA[
<?php
function latin1ToUTF8($str)
{
    return utf8_decode($str);
    // alternatively we could have used
    // return mb_convert_encoding($str, 'UTF-8', 'iso-8859-1');
}

function utf16ToUTF8($str)
{
    return mb_convert_encoding($str, 'UTF-8', 'UTF-16');
}

function windows1252ToUTF8($str)
{
    return mb_convert_encoding($str, 'UTF-8', 'windows-1252');
}

require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name', // name is in ISO-8859-1 and therefore will be handled by the default conversion
            'birth_year',
            'birth_place',
            'genre' => array(
                'value' => 'genre',
                'encoder' => false  // genre already is in UTF-8
            ),
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title' => array(
                        'value' => 'title',
                        'encoder' => 'utf16ToUTF8'  // title is in UTF-16 and therefore needs
                    ),                              // special treatment
                    'published_year'
                ),
                'attributes' => array(
                    'comment' => array(
                        'value' => 'comment',
                        'encoder' => 'windows1252ToUTF8'    // comment is in Windows-1252
                    )
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>

     </para>
    </refsect3>
  </refsect2>

  <refsect2 id="{@id return_value_modification}">
   <title>Modifying the returned DOMDocument instance</title>
   <para>
    {@link XML_Query2XML::getXML()} returns an instance of
    {@link http://www.php.net/manual/en/ref.dom.php#dom.class.domdocument DOMDocument}.
    I recommend that you do some reading about
    {@link http://www.php.net/manual/en/ref.dom.php PHP5's DOM extension}.
   </para>
   <para>
    Let's see how we can add attributes to the root element
    (i.e. the first child of the DOMDocument instance returned by {@link XML_Query2XML::getXML() getXML()}):
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

$doc = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre'
        )
    )
);
$root = $doc->firstChild;
$root->setAttribute('copyright', 'John Doe 2007');

header('Content-Type: application/xml');
$doc->formatOutput = true;
print $doc->saveXML();
?>
    ]]>
    </programlisting>
   </para>
   <para>
    This adds an attribute named 'copyright' with a value of 'John Doe 2007'
    to the root element &lt;music_library&gt;:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library copyright="John Doe 2007">
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
  </artist>
</music_library>
    ]]>
    </programlisting>
   </para>
  </refsect2>


  <refsect2 id="{@id final_notes}">
   <title>Final Notes on XML_Query2XML::getXML()</title>
   <para>
    You might also want to read the API docs: {@link XML_Query2XML}.
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="{@id other_xml_data_sources}">
  <title>Integrating other XML data sources</title>
  <refsect2 id="{@id intro}">
   <title>Introduction</title>
   <para>
    Since release 1.1.0 it is possible to integrate other XML data sources into
    the XML data that is returned by {@link XML_Query2XML::getXML()}. For example
    you might want to store XML data in your relational database and integrate that
    into your xml feed. In this case the XML data is only present in serialized form
    and therefore needs to be unserialized first. This means that the data has to be
    converted into a {@link http://www.php.net/manual/en/ref.dom.php DOMDocument} using
    {@link http://www.php.net/manual/en/function.dom-domdocument-loadxml.php DOMDocument::loadXML()}.
    It might as well be that you already have a PHP application running that creates a DOMDocument.
    In that case no unserialization is needed.
   </para>
  </refsect2>
  <refsect2 id="{@id unserialization_prefix}">
   <title>The unserialization prefix (&amp;)</title>
   <para>
    To unserialize xml data you can use the UNSERIALIZATION prefix &amp;. It has the following
    characteristics:
    <itemizedlist>
     <listitem>
      {@link http://www.php.net/manual/en/function.dom-domdocument-loadxml.php DOMDocument::loadXML()}
      is used for unserialization.
     </listitem>
     <listitem>
      If the data to unserialize is an empty string ('') or null the data will be silently
      ignored and no XML elements will be created.
     </listitem>
     <listitem>
      A XML_Query2XML_XMLException will be thrown if the unserialization fails, i.e.
      {@link http://www.php.net/manual/en/function.dom-domdocument-loadxml.php DOMDocument::loadXML()}
      returns false. This will happen for example if the data you try to unserialize is 'John Doe' (no xml tags at all),
      '&lt;name&gt;John Doe' (no closing tag) or '&lt;name&gt;John Doe&lt;/name&gt;&lt;name&gt;Jane Doe&lt;/name&gt;' (no root tag).
     </listitem>
    </itemizedlist>
   </para>
   <refsect3 id="{@id usage_scenarios}">
    <title>Usage scenarios of the unserialization prefix (&amp;)</title>
    <para>
     Regarding a container (the root element of your unserialized data)
     there are 3 different things you might want when unserializing
     the data:
     <itemizedlist>
      <listitem>
       Container always present
      </listitem>
      <listitem>
       Container only present if there are children
      </listitem>
      <listitem>
       No Container
      </listitem>
     </itemizedlist>
     For the detailed description of each of the three possibilities that is to follow, we will assume
     that your XML data is stored in the database. Therefore &amp; will be used in the form
     of '&amp;COLUMN_NAME'. If you wanted to unserialize static data you would write something
     like
     <programlisting role="php">
     <![CDATA[
'&:<name>John Doe</name>'
     ]]>
     </programlisting>
     or if you wanted to unserialize a string returned from a callback function, you would use
     <programlisting role="php">
     <![CDATA[
'&#MyClass::myFunction()'
     ]]>
     </programlisting>
     <itemizedlist>
      <listitem>
       <emphasis>Container always present</emphasis>: The container element will be present
       even if there is no data to be unserialized. This is the default behaviour:
       <programlisting role="php">
       <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom =& $query2xml->getXML(
    "SELECT
        *, NULL AS additional_xml
     FROM
        store",
    array(
        'rootTag' => 'music_stores',
        'rowTag' => 'store',
        'idColumn' => 'storeid',
        'elements' => array(
            'storeid',
            'country',
            'state',
            'city',
            'street',
            'building_xmldata' => '&building_xmldata',
            'additional_xml' => '&additional_xml',
        )
    )
);
$dom->formatOutput = true;
print $dom->saveXML();
?>
       ]]>
       </programlisting>
       For both records the 'building_xmldata' column contains a &lt;building&gt; element
       that has 3 children: &lt;floors&gt;, &lt;elevators&gt; and &lt;square_meters&gt;. But
       there is always a surrounding &lt;building_xmldata&gt; tag. The 'additional_xml' column
       is NULL for both records but an empty &lt;additional_xml/&gt; element gets created for
       both of them.
       <programlisting role="tutorial">
       <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_stores>
  <store>
    <storeid>1</storeid>
    <country>US</country>
    <state>New York</state>
    <city>New York</city>
    <street>Broadway &amp; 72nd Str</street>
    <building_xmldata>
      <building>
        <floors>4</floors>
        <elevators>2</elevators>
        <square_meters>3200</square_meters>
      </building>
    </building_xmldata>
    <additional_xml/>
  </store>
  <store>
    <storeid>2</storeid>
    <country>US</country>
    <state>New York</state>
    <city>Larchmont</city>
    <street>Palmer Ave 71</street>
    <building_xmldata>
      <building>
        <floors>2</floors>
        <elevators>1</elevators>
        <square_meters>400</square_meters>
      </building>
    </building_xmldata>
    <additional_xml/>
  </store>
</music_stores>
       ]]>
       </programlisting>
       Note: you would get exactly the same result by using the 'value' option within
       a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}
       instead of a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}.
       Instead of
       <programlisting role="php">
       <![CDATA[
'building_xmldata' => '&building_xmldata'
       ]]>
       </programlisting>
       you would write
       <programlisting role="php">
       <![CDATA[
'building_xmldata' => array(
    'value' => '&building_xmldata'
)
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>Container only present if there are children</emphasis>: The container will only be
       present if the unserialization produces at least one XML element. This is achieved
       by using the CONDITIONAL prefix (?):
       <programlisting role="php">
       <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom =& $query2xml->getXML(
    "SELECT
        *, NULL AS additional_xml
     FROM
        store",
    array(
        'rootTag' => 'music_stores',
        'rowTag' => 'store',
        'idColumn' => 'storeid',
        'elements' => array(
            'storeid',
            'country',
            'state',
            'city',
            'street',
            'building_xmldata' => '?&building_xmldata',
            'additional_xml' => '?&additional_xml',
        )
    )
);
$dom->formatOutput = true;
print $dom->saveXML();
?>
       ]]>
       </programlisting>
       The resulting XML data shows that the unserialized XML is still enclosed
       by a &lt;building_xmldata&gt; tag but the &lt;additional_xml&gt; elements are gone:
       <programlisting role="tutorial">
       <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_stores>
  <store>
    <storeid>1</storeid>
    <country>US</country>
    <state>New York</state>
    <city>New York</city>
    <street>Broadway &amp; 72nd Str</street>
    <building_xmldata>
      <building>
        <floors>4</floors>
        <elevators>2</elevators>
        <square_meters>3200</square_meters>
      </building>
    </building_xmldata>
  </store>
  <store>
    <storeid>2</storeid>
    <country>US</country>
    <state>New York</state>
    <city>Larchmont</city>
    <street>Palmer Ave 71</street>
    <building_xmldata>
      <building>
        <floors>2</floors>
        <elevators>1</elevators>
        <square_meters>400</square_meters>
      </building>
    </building_xmldata>
  </store>
</music_stores>
       ]]>
       </programlisting>
       Again: the same results can be achieved by using the 'value' option within
       a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}
       instead of a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}.
       Instead of
       <programlisting role="php">
       <![CDATA[
'building_xmldata' => '?&building_xmldata'
       ]]>
       </programlisting>
       you would write
       <programlisting role="php">
       <![CDATA[
'building_xmldata' => array(
    'value' => '?&building_xmldata'
)
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       <emphasis>No Container</emphasis>: Even if the unserialization produces an XML element
       no container will be used. You have to effectively hide the container by using the
       hidden_container_prefix that can be set using
       {@tutorial XML_Query2XML.pkg#global_options.setglobaloption} and defaults to '__'. Here
       goes an example:
       <programlisting role="php">
       <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom =& $query2xml->getXML(
    "SELECT
        *
     FROM
        store",
    array(
        'rootTag' => 'music_stores',
        'rowTag' => 'store',
        'idColumn' => 'storeid',
        'elements' => array(
            'storeid',
            'country',
            'state',
            'city',
            'street',
            '__building_xmldata' => '&building_xmldata'
        )
    )
);
$dom->formatOutput = true;
print $dom->saveXML();
?>
       ]]>
       </programlisting>
       The resulting XML now does not contain &lt;building_xmldata&gt; tags that surround
       the &lt;building&gt; elements:
       <programlisting role="tutorial">
       <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_stores>
  <store>
    <storeid>1</storeid>
    <country>US</country>
    <state>New York</state>
    <city>New York</city>
    <street>Broadway &amp; 72nd Str</street>
    <building>
      <floors>4</floors>
      <elevators>2</elevators>
      <square_meters>3200</square_meters>
    </building>
  </store>
  <store>
    <storeid>2</storeid>
    <country>US</country>
    <state>New York</state>
    <city>Larchmont</city>
    <street>Palmer Ave 71</street>
    <building>
      <floors>2</floors>
      <elevators>1</elevators>
      <square_meters>400</square_meters>
    </building>
  </store>
</music_stores>
       ]]>
       </programlisting>
       The same results can be achieved by using the 'value' option within
       a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}
       instead of a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}.
       Instead of
       <programlisting role="php">
       <![CDATA[
'__building_xmldata' => '&building_xmldata'
       ]]>
       </programlisting>
       you would write
       <programlisting role="php">
       <![CDATA[
'__building_xmldata' => array(
    'value' => '&building_xmldata'
)
       ]]>
       </programlisting>
       or (which is effectively the same)
       <programlisting role="php">
       <![CDATA[
'building_xmldata' => array(
    'rowTag' => '__building_xmldata'
    'value' => '&building_xmldata'
)
       ]]>
       </programlisting>
       Please also note that using the CONDITIONAL prefix (?) in conjunction with
       the hidden_container_prefix '__' does not change the resulting XML data in any way:
       <programlisting role="php">
       <![CDATA[
'__building_xmldata' => '?&building_xmldata'
       ]]>
       </programlisting>
      </listitem>
     </itemizedlist>
    </para>
   </refsect3>
   <refsect3 id="{@id writing_your_own}">
    <title>Writing your own unserialization method</title>
    <para>
     If you are unhappy with these chracteristics (e.g. you want invalid XML data to be ignored
     rather than causing an exception to be thrown) you could do your own unserialization using
     a CALLBACK FUNCTION (i.e. the # prefix). Here is what the unserialization performed by
     the &amp; prefix looks like
     <programlisting role="php">
     <![CDATA[
if (strlen($xmlData)) {
    $doc = new DOMDocument();
    if (!@$doc->loadXML($xmlData)) {
        throw new XML_Query2XML_XMLException(
            'Could not unserialize the following XML data: '
            . $ret
        );
    }
    return $doc->documentElement;
} else {
    return null;
}
     ]]>
     </programlisting>
    </para>
   </refsect3>
  </refsect2>
  <refsect2 id="{@id callbacks}">
   <title>Returning DOMNode instances from callbacks</title>
   <para>
    If you want to integrate XML_Query2XML with another PHP application that uses
    PHP5's {@link http://www.php.net/manual/en/ref.dom.php DOM},
    you can make your callbacks return an instance of
    {@link http://www.php.net/manual/en/ref.dom.php DOMNode} or an array of DOMNode instances.
   </para>
   <para>
    In the following example we return a &lt;unixtime&gt; tag from the callback function
    getTime(). It will be placed inside a &lt;time&gt; tag.
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom =& $query2xml->getXML(
    "SELECT
        *
     FROM
        album",
    array(
        'rootTag' => 'music_store',
        'rowTag' => 'album',
        'idColumn' => 'albumid',
        'elements' => array(
            'albumid',
            'title',
            'time' => '#getTime()'
        )
    )
);
$dom->formatOutput = true;
print $dom->saveXML();

function getTime()
{
    $dom = new DOMDocument();
    $unixtime = $dom->createElement('unixtime');
    $unixtime->appendChild($dom->createTextNode(time()));
    return $unixtime;
}
?>
    ]]>
    </programlisting>
    Have a look at the resulting XML data:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_store>
  <album>
    <albumid>1</albumid>
    <title>New World Order</title>
    <time>
      <unixtime>1167167461</unixtime>
    </time>
  </album>
  <album>
    <albumid>2</albumid>
    <title>Curtis</title>
    <time>
      <unixtime>1167167461</unixtime>
    </time>
  </album>
  <album>
    <albumid>3</albumid>
    <title>Shaft</title>
    <time>
      <unixtime>1167167461</unixtime>
    </time>
  </album>
</music_store>
    ]]>
    </programlisting>
    Now we modify the example so that getTime() returns multiple DOMNode instances in an array.
    We will also "hide" the surrounding element using the hidden_container_prefix that can be
    set using {@tutorial XML_Query2XML.pkg#global_options.setglobaloption} and defaults to '__':
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom =& $query2xml->getXML(
    "SELECT
        *
     FROM
        album",
    array(
        'rootTag' => 'music_store',
        'rowTag' => 'album',
        'idColumn' => 'albumid',
        'elements' => array(
            'albumid',
            'title',
            '__time' => '#getTime()'
        )
    )
);
$dom->formatOutput = true;
print $dom->saveXML();

function getTime()
{
    $dom = new DOMDocument();
    $unixtime = $dom->createElement('unixtime');
    $unixtime->appendChild($dom->createTextNode(time()));

    $rfc2822date = $dom->createElement('rfc2822date');
    $rfc2822date->appendChild($dom->createTextNode(date('r')));
    return array($unixtime, $rfc2822date);
}
?>
    ]]>
    </programlisting>
    The surrounding &lt;time&gt; element is now gone and we have both tags &lt;unixtime&gt;
    and &lt;rfc2822date&gt;:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_store>
  <album>
    <albumid>1</albumid>
    <title>New World Order</title>
    <unixtime>1167169325</unixtime>
    <rfc2822date>Tue, 26 Dec 2006 22:42:05 +0100</rfc2822date>
  </album>
  <album>
    <albumid>2</albumid>
    <title>Curtis</title>
    <unixtime>1167169325</unixtime>
    <rfc2822date>Tue, 26 Dec 2006 22:42:05 +0100</rfc2822date>
  </album>
  <album>
    <albumid>3</albumid>
    <title>Shaft</title>
    <unixtime>1167169325</unixtime>
    <rfc2822date>Tue, 26 Dec 2006 22:42:05 +0100</rfc2822date>
  </album>
</music_store>
    ]]>
    </programlisting>
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="{@id exception_handling}">
  <title>Exception Handling</title>
  <para>
   The public methods {@link XML_Query2XML::factory()}, {@link XML_Query2XML::getFlatXML()}
   and {@link XML_Query2XML::getXML()} all may throw exceptions. For production use you will
   have to implement the security principle "secure failure". This means that you will have to
   catch exceptions and deal with them. XML_Query2XML makes this task easy as all exceptions this
   package will ever throw extend {@link XML_Query2XML_Exception}. Therefore it is possible to catch all
   exceptions by catching {@link XML_Query2XML_Exception}:
  </para>
  <para>
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
try {
    require_once 'MDB2.php';
    $query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
    $dom = $query2xml->getXML(
      "SELECT * FROM artist",
      array(
        'rootTag' => 'favorite_artist',
        'idColumn' => 'artistid',
        'rowTag' => 'artist',
        'elements' => array(
            'name',
            'birth_year',
            'genre'
        )
      )
    );
    echo $dom->saveXML();
} catch(XML_Query2XML_Exception $e) {
    /*
    * log this exceptions
    * display some error message that does not disclose sensitive information
    */
}
?>
   ]]>
   </programlisting>
  </para>
  <para>
   Here is a list of the exceptions the public methods of XML_Query2XML will throw:
   <itemizedlist>
    <listitem>
     {@link XML_Query2XML::factory()}: {@link XML_Query2XML_DBException} and {@link XML_Query2XML_ConfigException}
    </listitem>
    <listitem>
     {@link XML_Query2XML::getFlatXML()}: {@link XML_Query2XML_DBException} and
     {@link XML_Query2XML_XMLException}
    </listitem>
    <listitem>
     {@link XML_Query2XML::getXML()}: {@link XML_Query2XML_DBException},
     {@link XML_Query2XML_XMLException} and {@link XML_Query2XML_ConfigException}
    </listitem>
   </itemizedlist>
   As you can see, XML_Query2XML_Exception itself is never thrown.
  </para>
  <para>
   To treat different exceptions differently you would write code like this:
<programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
try {
    require_once 'MDB2.php';
    $query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
    $dom = $query2xml->getXML(
      "SELECT * FROM artist",
      array(
        'rootTag' => 'favorite_artist',
        'idColumn' => 'artistid',
        'rowTag' => 'artist',
        'elements' => array(
            'name',
            'birth_year',
            'genre'
        )
      )
    );
    echo $dom->saveXML();
} catch(XML_Query2XML_DBException $e) {
    //handle DB error
} catch(XML_Query2XML_XMLException $e) {
    //handle XML error
} catch(XML_Query2XML_Exception $e) {
    /*
    * Handle all other errors/exceptions; this will not only catch
    * XML_Query2XML_ConfigException but also all other exceptions that might be
    * added in future releases of XML_Query2XML.
    */
}
?>
   ]]>
   </programlisting>
   Bottom line: make sure you at least have a catch block for XML_Query2XML_Exception.
  </para>
 </refsect1>

 <refsect1 id="{@id formatting}">
  <title>Output formatting</title>
  <para>
   Before calling the saveXML() method on your DOMDocument instance set its public property
   {@link http://at.php.net/manual/en/ref.dom.php#dom.class.domdocument.properties formatOutput} to true!
   Here goes an example:
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artist',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'name',
        'birth_year',
        'genre'
    )
  )
);
header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
   ]]>
   </programlisting>
  </para>
  <para>
   Alternatively you could also use {@link http://pear.php.net/package/XML_Beautifier PEAR XML_Beautifier}.
   Here goes an example:
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'favorite_artist',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'name',
        'birth_year',
        'genre'
    )
  )
);
header('Content-Type: application/xml');
print '<?xml version="1.0" encoding="UTF-8"?>' . "\n";

require_once 'XML/Beautifier.php';
$beautifier = new XML_Beautifier();
print $beautifier->formatString($dom->saveXML());
?>
   ]]>
   </programlisting>
  </para>
 </refsect1>

 <refsect1 id="{@id output_caching}">
  <title>Output Caching</title>
  <para>
   If your XML data is rather static in nature, i.e. exactely the same XML
   data is created over and over again you might want to use some kind of output caching.
   I will demonstrate the usage of {@link http://pear.php.net/package/Cache_Lite PEAR Cache_Lite} here:
  </para>
  <para>
   <programlisting role="php">
   <![CDATA[
<?php
require_once('Cache/Lite.php');
/*
* Set a id for this cache; if you generate the XML data based
* on values passed via POST/GET/COOKIE, include these values
* in $id. This does not need to be an integer; it's md5sum
* will be used.
*/
$id = '123';

//set a few options
$options = array(
    'cacheDir' => "/tmp/",
    'lifeTime' => 3600
);

//create a Cache_Lite object
$cache = new Cache_Lite($options);

// content type for xml data
header('Content-Type: application/xml');

//test if there is a valide cache for this id
if ($data = $cache->get($id)) {
    print $data;
} else {
    //no valid cache found
    require_once 'XML/Query2XML.php';
    require_once 'MDB2.php';
    $query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
    $dom = $query2xml->getXML(...);
    $dom->formatOutput = true;

    //cache the XML data
    $data = $dom->saveXML();
    $cache->save($data, $id);

    print $data;
}
?>
   ]]>
   </programlisting>
   For more information on PEAR Cache_Lite, please see the
   {@link http://pear.php.net/manual/en/package.caching.cache-lite.php Cache_Lite manual}.
  </para>
 </refsect1>

 <refsect1 id="{@id encoding}">
  <title>XML encoding</title>
  <para>
   It is highly recommended to use UTF-8 for your XML data. But if you want
   to use another encoding standard you have to:
   <itemizedlist>
    <listitem>
     Use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_encoder} to convert
     all node and attribute values to the desired encoding standard. If source and
     destination encoding standards are the same, you just have to set
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_encoder} to false.
    </listitem>
    <listitem>
     Set the encoding property of the DOMDocument instance returned by XML_Query2XML::getXML().
    </listitem>
   </itemizedlist>
  </para>
  <para>
    For some introduction to XML encoding please see
    {@link http://www.w3schools.com/xml/xml_encoding.asp} and
    {@link http://www.opentag.com/xfaq_enc.htm}.
    Note: I highly recommend to use UTF-8 for XML if you don't have a compelling reason
    to use an other encoding standard.
   </para>
  <para>
   Here goes an example that shows how to use ISO-8859-1 (Latin-1) for XML encoding. We
   will assume that your data is in ISO-8859-1 and therefore does not need any conversion.
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'encoder' => false,     // disable default ISO-8859-1 to UTF-8 encoding
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre'
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;

$dom->encoding = 'iso-8859-1';  //setting XML encoding

print $dom->saveXML();
?>
   ]]>
   </programlisting>
   This results in the following XML:
   <programlisting role="tutorial">
   <![CDATA[
<?xml version="1.0" encoding="iso-8859-1"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
  </artist>
</music_library>
   ]]>
   </programlisting>
  </para>
 </refsect1>


 <refsect1 id="{@id binary_data}">
  <title>Handling Binary Data</title>
  <para>
   If you want to include binary data (e.g. JPEG data) in XML data you should encode your binary data
   to make sure that it does not include a sequence of bytes that represent the characters "&lt;/"
   or a null byte (which usually denotes the end of a string). The most common binary data
   encoding for XML is base64. The most straightforward way to do base64 encoding for
   an element or attribute value is to use the BASE64 ENCODING shortcut '^'.
  </para>
  <para>
   In the following example we will assume that the column album.comment contains binary data:
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';

$mdb2 = MDB2::factory('mysql://root@localhost/Query2XML_Tests');
$query2xml = XML_Query2XML::factory($mdb2);

$dom = $query2xml->getXML(
    'SELECT * FROM album',
    array(
        'idColumn' => 'albumid',
        'rowTag' => 'album',
        'rootTag' => 'music_store',
        'elements' => array(
            'albumid',
            'title',
            'comment' => '^comment'
        )
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
   ]]>
   </programlisting>
   The resulting XML data looks like this:
   <programlisting role="tutorial">
   <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_store>
  <album>
    <albumid>1</albumid>
    <title>New World Order</title>
    <comment>dGhlIGJlc3QgZXZlciE=</comment>
  </album>
  <album>
    <albumid>2</albumid>
    <title>Curtis</title>
    <comment>dGhhdCBtYW4ncyBnb3Qgc29tdGhpbicgdG8gc2F5</comment>
  </album>
  <album>
    <albumid>3</albumid>
    <title>Shaft</title>
    <comment>aGUncyB0aGUgbWFu</comment>
  </album>
</music_store>
   ]]>
   </programlisting>
  </para>
 </refsect1>

 <refsect1 id="{@id dumpdatabase}">
  <title>Using dynamic $options to dump all data of your database</title>
  <para>
   For some reason you might simply want to dump every table in your database
   with all their records. If you don't want to go over your code everytime a
   new table was added, you need to generate (parts of) the $options argument on
   the fly. Here is one way to do it:
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';

$mdb2 = MDB2::factory('mysql://root@localhost/Query2XML_Tests');
$query2xml = XML_Query2XML::factory($mdb2);


//we need MDB2's manager module to get the list of tables in a database independent way
$mdb2->loadModule('Manager');
$elements = array();
$mdb2->setOption('portability', MDB2_PORTABILITY_NONE);
$tables = $mdb2->listTables();
$mdb2->setOption('portability', MDB2_PORTABILITY_ALL);
for ($i = 0; $i < count($tables); $i++) {
    $elements['table' . $i] = array(
        'rowTag' => 'table',
        'attributes' => array(
            'name' => ':' . $tables[$i]
        ),
        'elements' => array(
            'record' => array(
                'idColumn' => false,
                'sql' => 'SELECT * FROM ' . $tables[$i],
                'elements' => array(
                    '*'
                )
            )
        )
    );
}

$dom = $query2xml->getXML(
    false,
    array(
        'idColumn' => false,
        'rowTag' => '__tables',
        'rootTag' => 'database',
        'elements' => $elements
    )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
   ]]>
   </programlisting>
  </para>
  <para>
   Notice how we used MDB2's manager module to get a list of all tables in our database.
   We then loop over the names and create
   {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements}
   at run time.
  </para>
  <para>
   Side note: unfortunately MDB2's portability feature per default makes listTabes() return all table names lower-cased.
   To circumvent this we have to temporarily change the portability option. See {@link http://pear.php.net/bugs/bug.php?id=11215}
   which describes the issue in greater detail.
  </para>
  <para>
   Each table tag will have an attribute "name". We use the ':' prefix to indicate that
   what follows is a static text not to be interpreted as a column name.
  </para>
  <para>
   When looking at the getXML() call, you'll notice that we didn't pass a query as the
   first argument ({@tutorial XML_Query2XML.pkg#query2xml_getxml.sql}) but rather a boolean
   value of false. As documented at {@tutorial XML_Query2XML.pkg#query2xml_getxml.sql}
   this will make XML_Query2XML behave as if we used a query that returned a single record
   with no columns. This is necessary because in our example we use multiple unrelated queries
   that we simply want to palce inside a database tag.
  </para>
  <para>
   Also notice that we use the boolean value of FALSE for
   {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn}
   at the root level and for each of the
   tables. It is OK to do so on the root level because we are actually only dealing with a
   single fake record there. To use FALSE for {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn}
   on the sub-levels within the $elements array
   generated at run-time is also OK because we will always want all records and (which is
   the reason why we are not violating best practices) we simply don't know the primary key
   columns for all tables that might get created in the future.
  </para>
  <para>
   Also note that we used '__tables' for {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_rowtag}
   at the root level: this is because we don't have anything to loop over at the root level - remember
   using false for {@tutorial XML_Query2XML.pkg#query2xml_getxml.sql} is like using a
   query that returns a single record with no columns.
  </para>
 </refsect1>

 <refsect1 id="{@id without_prefixes}">
  <title>Working without Shortcuts and Prefixes</title>
  <para>
   You think having to deal with all these different prefixes (e.g. #, ?, :, &amp;, ^ and =) when defining
   {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_value} and
   {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}
   just makes things more complicated or your code less readable? In that case, just don't use them! Below is
   way of getting almost the same functionality with a command object pattern implementation. If you have
   to deal with some 10,000+ records in your XML, using command objects might even improve performance
   a little bit (~1-3%).
  </para>
  <para>
   The following example first provides command classes that implement the functionality
   of the currently available prefixes.
   <programlisting role="php">
   <![CDATA[
<?php
/**All command objects have to implement the interface XML_Query2XML_Callback.
*/
require_once 'XML/Query2XML/Callback.php';

/**All command classes that work on a single column value will extend this abstract class.
* Classes extending this class will have to implement the execute(array $record) method
* defined by the XML_Query2XML_Callback interface.
*/
abstract class Callback_SingleColumn implements XML_Query2XML_Callback
{
    /**The column name
    * @var string
    */
    protected $_column = '';

    /**Constructor
    * @param string $column The name of the column this instance will work on.
    */
    public function __construct($column)
    {
        $this->_column = $column;
    }

    /**Get the value of the column passed to the constructor.
    * @param array $record An associative array as it will be passed
    *                      to the execute(array $record) method.
    * @throws XML_Query2XML_Exception If the column name passed
    *                      to the constructor was not found in $record.
    */
    protected function _getColumnValue(array $record)
    {
        if (array_key_exists($this->_column, $record)) {
            return $record[$this->_column];
        }
        throw new XML_Query2XML_Exception(
            'Column ' . $this->_column . ' was not found in the result set'
        );
    }
}

/**Use an instance of this class to get the base64 encoded value of a column.
*/
class Callback_Base64 extends Callback_SingleColumn
{
    /**Called by XML_Query2XML for every record.
    * @param array $record An associative array.
    * @return string
    */
    public function execute(array $record)
    {
        return base64_encode($this->_getColumnValue($record));
    }
}

/**Use an instance of this class to unserialize XML data stored in a column.
*/
class Callback_Unserialization extends Callback_SingleColumn
{
    /**Called by XML_Query2XML for every record.
    * @param array $record An associative array.
    * @return DOMElement
    * @throws XML_Query2XML_XMLException If unserialization fails.
    */
    public function execute(array $record)
    {
        $doc = new DOMDocument();
        $xml = $this->_getColumnValue($record);
        if (!@$doc->loadXML($xml)) {
            throw new XML_Query2XML_XMLException(
                'Could not unserialize the following XML data: '
                . $xml
            );
        }
        return $doc->documentElement;
    }
}

/**Use an instance of this class to place a CDATA section around the value of a column.
*/
class Callback_CDATA extends Callback_SingleColumn
{
    /**Called by XML_Query2XML for every record.
    * @param array $record An associative array.
    * @return DOMCDATASection
    */
    public function execute(array $record)
    {
        $doc = new DOMDocument();
        return $doc->createCDATASection($this->_getColumnValue($record));
    }
}

/**Use an instance of this class to return a static data.
*/
class Callback_StaticData implements XML_Query2XML_Callback
{
    /**The static data
    * @var mixed
    */
    private $_data = null;

    /**Constructor
    * @param mixed $data The static date to return for every record.
    */
    public function __construct($data)
    {
        $this->_data = $data;
    }

    /**Called by XML_Query2XML for every record.
    * This method will always return the same data, no matter what
    * is passed as $record.
    *
    * @param array $record An associative array.
    * @return mixed
    */
    public function execute(array $record)
    {
        return $this->_data;
    }
}

require_once 'XML/Query2XML.php';
require_once 'MDB2.php';

$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

$xml = $query2xml->getXML(
    'SELECT * FROM store',
    array(
        'rootTag' => 'stores',
        'rowTag' => 'store',
        'idColumn' => 'storeid',
        'elements' => array(
            'base64' => new Callback_Base64('building_xmldata'),
            'cdata' => new Callback_CDATA('building_xmldata'),
            'static' => new Callback_StaticData('my static data'),
            'unserialized' => new Callback_Unserialization('building_xmldata')
        )
    )
);

$xml->formatOutput = true;
print $xml->saveXML();
?>
    ]]>
    </programlisting>
    Note that the above code is equivalent to
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';

$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

$xml = $query2xml->getXML(
    'SELECT * FROM store',
    array(
        'rootTag' => 'stores',
        'rowTag' => 'store',
        'idColumn' => 'storeid',
        'elements' => array(
            'base64' => '?^building_xmldata',
            'cdata' => '=building_xmldata',
            'static' => ':my static data',
            'unserialized' => '&building_xmldata'
        )
    )
);

$xml->formatOutput = true;
print $xml->saveXML();
?>
    ]]>
    </programlisting>
    Both produce the following XML data:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<stores>
  <store>
    <base64>PGJ1aWxkaW5nPjxmbG9vcnM+NDwvZmxvb3JzPjxlbGV2YXRvcnM+MjwvZWxldmF0b3JzPjxzcXVhcmVfbWV0ZXJzPjMyMDA8L3NxdWFyZV9tZXRlcnM+PC9idWlsZGluZz4=</base64>
    <cdata>< ![CDATA[<building><floors>4</floors><elevators>2</elevators><square_meters>3200</square_meters></building>]] ></cdata>
    <static>my static data</static>
    <unserialized>
      <building>
        <floors>4</floors>
        <elevators>2</elevators>
        <square_meters>3200</square_meters>
      </building>
    </unserialized>
  </store>
  <store>
    <base64>PGJ1aWxkaW5nPjxmbG9vcnM+MjwvZmxvb3JzPjxlbGV2YXRvcnM+MTwvZWxldmF0b3JzPjxzcXVhcmVfbWV0ZXJzPjQwMDwvc3F1YXJlX21ldGVycz48L2J1aWxkaW5nPg==</base64>
    <cdata>< ![CDATA[<building><floors>2</floors><elevators>1</elevators><square_meters>400</square_meters></building>]] ></cdata>
    <static>my static data</static>
    <unserialized>
      <building>
        <floors>2</floors>
        <elevators>1</elevators>
        <square_meters>400</square_meters>
      </building>
    </unserialized>
  </store>
</stores>
    ]]>
    </programlisting>
  </para>
  <para>
   Finally, note that you may also explecitely unregister a specific prefix using {@link XML_Query2XML::unregisterPrefix()}
   are unregister all previously defined prefixes using {@link XML_Query2XML::unregisterAllPrefixes()}.
  </para>
 </refsect1>

 <refsect1 id="{@id your_own_prefixes}">
  <title>Defining your own Prefixes</title>
  <para>
   You may want to define your own prefixes in order to have a simple and quick way to invoke complex functionality you need often.
   The registration of the prefix is very much straight forward:
  </para>
  <para>
   {@link XML_Query2XML::registerPrefix() XML_Query2XML::registerPrefix}($prefix, $className, $filePath = '')
  </para>
  <para>
   Note that you may also register a prefix that has been registered before (or is registered by default).
   In that case, the new registration will simply overwrite the old one.
  </para>
  <para>
   More difficult than simply registering the prefix, is writing the class that will implement its functionality.
   All such classes will have to implement the interface {@link XML_Query2XML_Data}. However, in practice you will
   want to extend one of the following abstract classes, depending on the type of functionality you need:
   <itemizedlist>
    <listitem>
     <emphasis>{@link XML_Query2XML_Data_Processor}</emphasis>: extend this class if you want to use any data
      as input other than the string specified right after the prefix. For example, if you want to use a column
      value as input data, extend this class and let the built-in code handle the rest. (Note: the
      BASE64 ENCODING prefix ^, CDATA SECTION prefix =, and the XML UNSERIALIZATION prefix &amp; are built using
      this class.)
    </listitem>
    <listitem>
     <emphasis>{@link XML_Query2XML_Data_Source}</emphasis>: extend this class if you only want to use the string
     specified right after the prefix as your data source. (Note: the STATIC TEXT prefix : and the CALLBACK FUNCTION
     prefix # are built using this class.)
    </listitem>
    <listitem>
     <emphasis>{@link XML_Query2XML_Data_Condition}</emphasis>: extend this class if you want to implement some
     kind of condition that will determine whether the XML element for which the value was to be used will be
     included in the resulting output. (Note: the CONDITIONAL prefix ? is built using this class.)
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Now, let's suppose you want to use the prefix "§" for your command class Year2UnixTime which calculates
   the Unix time (seconds since the Unix Epoch, January 1 1970 00:00:00 GMT) from a given year. In such a
   case you clearly want to extend {@link XML_Query2XML_Data_Processor}:
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/Data/Processor.php';
require_once 'MDB2.php';

class Year2UnixTime extends XML_Query2XML_Data_Processor
{
    /**
     * Create a new instance of this class.
     *
     * @param mixed  $preProcessor The pre-processor to be used. An instance of
     *                             XML_Query2XML_Data or null.
     * @param string $configPath   The configuration path within the $options
     *                             array.
     *
     * @return XML_Query2XML_Data_Processor_Base64
     */
    public function create($preProcessor, $configPath)
    {
        $processor = new Year2UnixTime($preProcessor);
        // The create() method of every class extending
        // XML_Query2XML_Data_Processor has to call
        // setConfigPath() manually!
        $processor->setConfigPath($configPath);
        return $processor;
    }

    /**
     * Called by XML_Query2XML for every record in the result set.
     *
     * @param array $record An associative array.
     *
     * @return string The base64-encoded version the string returned
     *                by the pre-processor.
     * @throws XML_Query2XML_ConfigException If the pre-processor returns
     *                something that cannot be converted to a string
     *                (i.e. an object or an array).
     */
    public function execute(array $record)
    {
        $data = $this->runPreProcessor($record);
        if (is_array($data) || is_object($data)) {
            throw new XML_Query2XML_ConfigException(
                $this->getConfigPath()
                . ': XML_Query2XML_Data_Processor_Base64: string '
                . 'expected from pre-processor, but ' . gettype($data) . ' returned.'
            );
        }
        return DateTime::createFromFormat('Y-m-d H:i:s', $data . '-01-01 00:00:00', new DateTimeZone('Etc/GMT+0'))->format('U');
    }
}

$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$query2xml->registerPrefix('§', 'Year2UnixTime');
$dom = $query2xml->getXML(
  "SELECT * FROM artist",
  array(
    'rootTag' => 'artists',
    'idColumn' => 'artistid',
    'rowTag' => 'artist',
    'elements' => array(
        'name',
        'birth_year',
        'birth_year_in_unix_time' => '§birth_year'
    )
  )
);

header('Content-Type: application/xml');
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    The resulting XML data looks like this:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<artists>
  <artist>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_year_in_unix_time>-1577923200</birth_year_in_unix_time>
  </artist>
  <artist>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_year_in_unix_time>-883612800</birth_year_in_unix_time>
  </artist>
  <artist>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_year_in_unix_time>-1262304000</birth_year_in_unix_time>
  </artist>
</artists>
   ]]>
   </programlisting>
  </para>
 </refsect1>

 <refsect1 id="{@id global_options}">
  <title>Global Options</title>
  <para>
   Global options can be set using the public method
   {@tutorial XML_Query2XML.pkg#global_options.setglobaloption} and retrieved using
   {@tutorial XML_Query2XML.pkg#global_options.getglobaloption}. Currently the
   following global options are available:
   <itemizedlist>
    <listitem>
     {@tutorial XML_Query2XML.pkg#global_options.hidden_container_prefix}
    </listitem>
   </itemizedlist>
  </para>
  <refsect2 id="{@id setglobaloption}">
   <title>XML_Query2XML::setGlobalOption()</title>
   <para>
    {@link XML_Query2XML::setGlobalOption() XML_Query2XML::setGlobalOption}($option, $value)
   </para>
   <para>
    Currently there is only one global option: {@tutorial XML_Query2XML.pkg#global_options.hidden_container_prefix}
    which has to be set to a non empty string. If you try to set a non existing global option or
    try to set an existing one to an invalid value a {@link XML_Query2XML_ConfigException}
    will be thrown.
   </para>
   <para>
    Here goes an example:
    <programlisting role="php">
    <![CDATA[
$query2xml =& XML_Query2XML::factory($db);
$query2xml->setGlobalOption('hidden_container_prefix', '___');
    ]]>
    </programlisting>
   </para>
  </refsect2>
  <refsect2 id="{@id getglobaloption}">
   <title>XML_Query2XML::getGlobalOption()</title>
   <para>
    {@link XML_Query2XML::getGlobalOption() XML_Query2XML::getGlobalOption}($option)
   </para>
   <para>
    Currently there is only one global option: {@tutorial XML_Query2XML.pkg#global_options.hidden_container_prefix}.
    Use getGlobalOption() to retrieve a global option's current value:
    <programlisting role="php">
    <![CDATA[
$query2xml =& XML_Query2XML::factory($db);
echo $query2xml->getGlobalOption('hidden_container_prefix');
    ]]>
    </programlisting>
    If you try to retrieve the value of a non existing global option a
    {@link XML_Query2XML_ConfigException} will be thrown.
   </para>
  </refsect2>
  <refsect2 id="{@id hidden_container_prefix}">
   <title>hidden_container_prefix</title>
   <para>
    All elements whose name start with the string specified in the
    hidden_container_prefix option are stripped from the DOMDocument that is finally
    returned by {@tutorial XML_Query2XML.pkg#query2xml_getxml}. The container's child
    elements are effectively replacing their parent. The default value of the
    hidden_container_prefix option is '__'.
    Here is an example using the default:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom =& $query2xml->getXML(
    "SELECT
        *
     FROM
        album",
    array(
        'rootTag' => 'music_store',
        'rowTag' => 'album',
        'idColumn' => 'albumid',
        'elements' => array(
            'albumid',
            'title',
            '__info' => '&:<name>John Doe</name>'
        )
    )
);
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    Instead of
    <programlisting role="php">
    <![CDATA[
'__info' => '&:<name>John Doe</name>'
    ]]>
    </programlisting>
    we also could have written
    <programlisting role="php">
    <![CDATA[
'name' => ':John Doe'
    ]]>
    </programlisting>
    Both versions produce the same XML data. Note how the contents of the &lt;__info&gt;
    element effectively replaced the &lt;__info&gt; tag itself. It results in the &lt;name&gt; element
    being directly placed inside the &lt;album&gt; element.
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_store>
  <album>
    <albumid>1</albumid>
    <title>New World Order</title>
    <name>John Doe</name>
  </album>
  <album>
    <albumid>2</albumid>
    <title>Curtis</title>
    <name>John Doe</name>
  </album>
  <album>
    <albumid>3</albumid>
    <title>Shaft</title>
    <name>John Doe</name>
  </album>
</music_store>
    ]]>
    </programlisting>
   </para>
   <para>
    Now imagine that we actually do want an XML element to be named '__info'. This
    means that we have to change the hidden_container_prefix option:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$query2xml->setGlobalOption('hidden_container_prefix', '___');
$dom =& $query2xml->getXML(
    "SELECT
        *
     FROM
        album",
    array(
        'rootTag' => 'music_store',
        'rowTag' => 'album',
        'idColumn' => 'albumid',
        'elements' => array(
            'albumid',
            'title',
            '__info' => '&:<name>John Doe</name>', //will not be hidden
            '___info' => '&:<name>John Doe</name>' //will be hidden
        )
    )
);
$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    This produces the following XML data:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_store>
  <album>
    <albumid>1</albumid>
    <title>New World Order</title>
    <__info>
      <name>John Doe</name>
    </__info>
    <name>John Doe</name>
  </album>
  <album>
    <albumid>2</albumid>
    <title>Curtis</title>
    <__info>
      <name>John Doe</name>
    </__info>
    <name>John Doe</name>
  </album>
  <album>
    <albumid>3</albumid>
    <title>Shaft</title>
    <__info>
      <name>John Doe</name>
    </__info>
    <name>John Doe</name>
  </album>
</music_store>
    ]]>
    </programlisting>
   </para>
  </refsect2>
 </refsect1>
 <refsect1 id="{@id debugging}">
  <title>Logging and Debugging XML_Query2XML</title>
  <para>
  	If you need to debug your XML_Query2XML or an application using it, use {@link XML_Query2XML::enableDebugLog()}
  	and {@link XML_Query2XML::disableDebugLog()}. It is recommended to use
  	{@link http://pear.php.net/package/Log PEAR Log}.
  </para>
  <para>
  	The following information is logged:
     <itemizedlist>
      <listitem>
       the beginning of the execution of a SQL query in the database:
       this includes the SQL statement itself followed by the values used
       when executing a prepared statement.
      </listitem>
      <listitem>
       the end of the execution of a SQL query in the database
      </listitem>
      <listitem>
       caching of a query's result
      </listitem>
      <listitem>
       retrieving previously cached data
      </listitem>
     </itemizedlist>
     When using PEAR::Log, the date, time, a custom string and '[info]' will preceed every
     entry.
  </para>
  <para>
   Here is how it's done:
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
$query2xml = XML_Query2XML::factory($db);

//create a new instance of PEAR::Log
require_once 'Log.php';
$debugLogger = Log::factory('file', 'debug.log', 'XML_Query2XML');

//start debugging
$query2xml->enableDebugLog($debugLogger);

$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
     ORDER BY
        artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'name',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'title'
                )
            )
        )
    )
);
print $dom->saveXML();
?>
   ]]>
   </programlisting>
   This will write the following to debug.log:
   <![CDATA[
Apr 18 20:54:30 XML_Query2XML [info] QUERY: SELECT
        *
     FROM
        artist
     ORDER BY
        artistid
Apr 18 20:54:30 XML_Query2XML [info] DONE
Apr 18 20:54:30 XML_Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:1
Apr 18 20:54:30 XML_Query2XML [info] DONE
Apr 18 20:54:30 XML_Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:2
Apr 18 20:54:30 XML_Query2XML [info] DONE
Apr 18 20:54:30 XML_Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:3
Apr 18 20:54:30 XML_Query2XML [info] DONE
   ]]>
   XML_Query2XML simply logs the SQL SELECT string the way it was passed to getXML(), including all
   whitespace characters. If the query in question is a complex join over multiple tables this
   might be a good thing. On the other hand you might just want to have a single line per log entry.
   This is best achieved by building a wrapper around PEAR Log:
   <programlisting role="php">
   <![CDATA[
class MyLogger {
    private $_logger = null;
    public function __construct($logger)
    {
        $this->_logger = $logger;
    }

    public function log($msg)
    {
        $this->_logger->log(preg_replace('/\n\ +/m', ' ', $msg));
    }
}
   ]]>
   </programlisting>
   Using this wrapper like this:
   <programlisting role="php">
   <![CDATA[
$query2xml->enableDebugLog(
    new MyLogger(
        Log::factory('file', 'debug.log', 'XML_Query2XML')
    )
);
   ]]>
   </programlisting>
   will make the log file from the prvious example look like this:
   <![CDATA[
Apr 18 20:55:51 XML_Query2XML [info] QUERY: SELECT * FROM artist ORDER BY artistid
Apr 18 20:55:51 XML_Query2XML [info] DONE
Apr 18 20:55:51 XML_Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:1
Apr 18 20:55:51 XML_Query2XML [info] DONE
Apr 18 20:55:51 XML_Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:2
Apr 18 20:55:51 XML_Query2XML [info] DONE
Apr 18 20:55:51 XML_Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:3
Apr 18 20:55:51 XML_Query2XML [info] DONE
   ]]>
   Note how the first query is now placed on a single line.
  </para>

  <refsect2 id="{@id enabledebuglog}">
   <title>XML_Query2XML::enableDebugLog()</title>
   <para>
    Please see the API docs at {@link XML_Query2XML::enableDebugLog()}.
   </para>
  </refsect2>

  <refsect2 id="{@id disabledebuglog}">
   <title>XML_Query2XML::disableDebugLog()</title>
   <para>
    Please see the API docs at {@link XML_Query2XML::disableDebugLog()}.
   </para>
  </refsect2>

 </refsect1>

 <refsect1 id="{@id profiling}">
  <title>Profiling and Performance Tuning</title>
  <para>
  	When the amount of data you have to deal with is getting bigger and bigger you will start to ask yourself
  	questions like:
  	<itemizedlist>
     <listitem>
  	  Are two smaller joins faster than a single huge one?
  	 </listitem>
  	 <listitem>
  	  Should I use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql} with or without caching?
  	 </listitem>
  	 <listitem>
  	  How often does a certain query get executed and how long does it take?
  	 </listitem>
  	</itemizedlist>
  	XML_Query2XML's profiling provides help on giving answers to these questions.
  </para>

  <refsect2 id="{@id example}">
   <title>Example</title>
   <para>
     {@tutorial XML_Query2XML.pkg#profiling.startprofiling} should be the first and
     {@tutorial XML_Query2XML.pkg#profiling.getprofile} the last method you call on your XML_Query2XML instance.
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
$query2xml = XML_Query2XML::factory($db);

//start the profiling as soon as possible
$query2xml->startProfiling();

//do the real work
$dom = $query2xml->getXML(...);
print $dom->saveXML();

//save the profile in a separate file
require_once 'File.php';
$fp = new File();
$fp->write('/tmp/query2xml_profile.txt', $query2xml->getProfile(), FILE_MODE_WRITE);
?>
     ]]>
     </programlisting>
   </para>
  </refsect2>

  <refsect2 id="{@id startprofiling}">
   <title>XML_Query2XML::startProfiling()</title>
   <para>
     {@link XML_Query2XML::startProfiling()} will start the profiling by
     initializing the private variable {@link XML_Query2XML::$_profile}. See
     {@tutorial XML_Query2XML.pkg#profiling.getrawprofile} for details on its data format.
   </para>
  </refsect2>

  <refsect2 id="{@id stopprofiling}">
   <title>XML_Query2XML::stopProfiling()</title>
   <para>
     {@link XML_Query2XML::stopProfiling()} will stop the profiling. In most cases you will not
     need to call this method as {@tutorial XML_Query2XML.pkg#profiling.getprofile} will do so implicitly.
   </para>
  </refsect2>

  <refsect2 id="{@id getprofile}">
   <title>XML_Query2XML::getProfile()</title>
   <para>
     {@link XML_Query2XML::getProfile()} will return the profile as a multiline string.
     It is a table with the following columns:
     <itemizedlist>
      <listitem>
       FROM_DB: number of times this type of query executed in the database
      </listitem>
      <listitem>
       FROM_CACHE: number of times the results could be retrieved from cache
      </listitem>
      <listitem>
       CACHED: whether caching was performed (true or false); if caching was performed but FROM_CACHE
       is 0, the value will be "true!" to indicate that no caching is necessary
      </listitem>
      <listitem>
       AVG_DURATION: average duration of executing the query and getting it's results
      </listitem>
      <listitem>
       DURATION_SUM: total duration for all queries of this type
      </listitem>
      <listitem>
       SQL: the query itself
      </listitem>
     </itemizedlist>
     Additionally there will be a summary at the end of the file. It will contain two fields:
     <itemizedlist>
      <listitem>
       TOTAL_DURATION: number of seconds the whole operation took (including outputting everything).
       Whether you output the generated XML data will only affect TOTAL_DURATION but not DB_DURATION.
      </listitem>
      <listitem>
       DB_DURATION: number of seconds spent executing SQL queries and retrieving their results.
      </listitem>
     </itemizedlist>
   </para>
  </refsect2>

  <refsect2 id="{@id getrawprofile}">
   <title>XML_Query2XML::getRawProfile()</title>
   <para>
     {@link XML_Query2XML::getRawProfile()} will return the raw profile data as a multi dimensional associative array.
     It has the following format:

     <programlisting role="php">
     <![CDATA[
$this->_profile = array(
    'queries'    => array(),
    'start'      => microtime(1),
    'stop'       => 0,
    'duration'   => 0,
    'dbStop'     => 0,
    'dbDuration' => 0
);
     ]]>
     </programlisting>
     The element 'queries' is itself an associative array that
     uses $sql as the array key;:
     <programlisting role="php">
     <![CDATA[
$this->_profile['queries'][$sql] = array(
    'fromDB' => 0,
    'fromCache' => 0,
    'cached' => false,
    'runTimes' => array()
);
     ]]>
     </programlisting>
     The element 'runTimes' is an indexed array that stores multiple
     arrays that have the following format:
     <programlisting role="php">
     <![CDATA[
array('start' => microtime(true), 'stop' => 0);
     ]]>
     </programlisting>
   </para>
  </refsect2>

  <refsect2 id="{@id clearprofile}">
   <title>XML_Query2XML::clearProfile()</title>
   <para>
    Please see the API docs at {@link XML_Query2XML::clearProfile()}.
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="{@id ldap}">
  <title>The LDAP Driver</title>
  <para>
   Since v1.6.0RC1 XML_Query2XML comes with a driver for {@link http://pear.php.net/package/Net_LDAP PEAR Net_LDAP}.
   The driver for {@link http://pear.php.net/package/Net_LDAP2 PEAR Net_LDAP2} is available since v1.7.0RC1.
   This allows you to use LDAP instead of an RDBMS as your primary data source. To use the PEAR Net_LDAP
   driver you can pass an instance of Net_LDAP to {@tutorial XML_Query2XML.pkg#query2xml_factory}. The only
   thing that changes is the format of {@tutorial XML_Query2XML.pkg#query2xml_getxml.sql} and
   {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}.
  </para>
  <refsect2 id="{@id queryspecification}">
   <title>LDAP Query Specification</title>
   <para>
    All LDAP queries have to be specified as an array.
    LDAP query specifications can be used
    for {@tutorial XML_Query2XML.pkg#query2xml_getxml.sql} and
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}. They look as follows:
    <programlisting role="php">
    <![CDATA[
array(
    'data' => array(...),  // optional; only relevant if placeholders are used in 'base' or 'filter'
    'base' => 'ou=peopole,dc=example,dc=com',
    'filter' => '(objectclass=inetOrgPerson)',
    'options' => array(
        'attributes' => array(
            ...
        ), ...
    )
)
    ]]>
    </programlisting>
    These are the arguments as they will be passed to
    {@link http://pear.php.net/package/Net_LDAP/docs/latest/Net_LDAP/Net_LDAP.html#methodsearch Net_LDAP::search()}.
    Please see the {@link http://pear.php.net/manual/en/package.networking.net-ldap.search.php Net_LDAP manual}
    for details.
   </para>
   <para>
    Note that $ldapQuery['options']['attributes'] will be used by the LDAP driver if it is present. It allows the driver
    to set the specified attributes to null if they are not present in the returned records.
    It is therefore highly recommended to always set the option 'attributes'.
    See {@tutorial XML_Query2XML.pkg#ldap.optionalattributes} for details.
    <programlisting role="php">
    <![CDATA[
array(
    'base' => 'ou=peopole,dc=example,dc=com',
    'filter' => '(objectclass=inetOrgPerson)',
    'options' => array(
        'attributes' => array(
            'cn',
            'mobile'
        )
    )
)
    ]]>
    </programlisting>
   </para>
   <para>
    Now let's look at an example. We want all entries from ou=people,dc=example,dc=com that
    have an objectclass of inetOrgPerson. For each of these entries we want to output
    the attributes cn and mobile.
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'Net/LDAP.php';

/*
* just pass an instance of Net_LDAP to the factory method
* as you would do it with an MDB2 or PDO instance.
*/
$query2xml = XML_Query2XML::factory(Net_LDAP::connect());

$dom = $query2xml->getXML(
    array(  //this is different than what you're used to from the other drivers
        'base' => 'ou=people,dc=example,dc=com',
        'filter' => '(objectclass=inetOrgPerson)',
        'options' => array(
            'attributes' => array( //to tell the LDAP driver which columns to watch out for
                'cn',
                'mobile',
            )
        )
    ),
    array(
        'rootTag' => 'employees',
        'idColumn' => 'cn',
        'rowTag' => 'employee',
        'elements' => array(
            'cn',
            'mobile'
        )
    )
);
header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    This would produce the following XML data:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<employees>
  <employee>
    <cn>John Doe</cn>
    <mobile>666-777-888</mobile>
  </employee>
  <employee>
    <cn>Jane Doe</cn>
    <mobile>555-777-888</mobile>
  </employee>
</employees>
    ]]>
    </programlisting>
   </para>
   <para>
    An LDAP Query Specification that makes use of placeholders and the option 'data' looks like this:
    <programlisting role="php">
    <![CDATA[
array(
    'data' => array(':John Doe'),
    'base' => 'ou=peopole,dc=example,dc=com',
    'filter' => '(&(objectclass=inetOrgPerson)(cn=?))',
    'options' => array(
        'attributes' => array(
            'cn',
            'mobile'
        ),
        'query2xml_placeholder' => '?'
    )
)
    ]]>
    </programlisting>
    An LDAP query specification provides a prepare&amp;execute-like funktionality: a placeholder
    (by default a question mark) can be used in ['base'] and ['filter'].
    That placeholder will be replaced with the values from ['data'].
    Please note that a placeholder will only be treated as such if there is a corresponsing element
    in the 'data' array. That means that if the 'data' array has only one element and 'base' and
    'filter' contain more than one quesion mark, all but the first quesion mark will not be replaced.
   </para>
   <para>
    Also note that there is another option the LDAP driver will understand:
    'query2xml_placeholder'. It allows you to define the placeholder used in 'base' and 'filter'. The default
    is a question mark ('?'). The placeholder you define can also consist of multiple chracters.
   </para>
   <para>
    Let's have a look at a full example: we want all entries of the class inetOrgPerson that have a cn attribute
    that contains the string submitted vi $_GET['cn']. Please note that the LDAP driver internally uses
    {@link http://pear.php.net/package/Net_LDAP/docs/latest/Net_LDAP/Net_LDAP_Util.html#methodescape_filter_value Net_LDAP_Util::escape_filter_value()}
    for all elements of the 'data' array to prevent injection attacks.
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'Net/LDAP.php';

$query2xml = XML_Query2XML::factory(Net_LDAP::connect());

$dom = $query2xml->getXML(
    array(
        'data' => array(':' . $_GET['cn']),
        'base' => 'ou=people,dc=example,dc=com',
        'filter' => '(&(objectclass=inetOrgPerson)(cn=*?*))', //the question mark will be replace
                                                              //with the contents of $_GET['cn']
        'options' => array(
            'attributes' => array( //to tell the LDAP driver which columns to watch out for
                'cn',
                'mobile',
            )
        )
    ),
    array(
        'rootTag' => 'employees',
        'idColumn' => 'cn',
        'rowTag' => 'employee',
        'elements' => array(
            'cn',
            'mobile'
        )
    )
);
header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    if $_GET['cn'] was set to 'John' the following XML data would be produced:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<employees>
  <employee>
    <cn>John Doe</cn>
    <mobile>666-777-888</mobile>
  </employee>
</employees>
    ]]>
    </programlisting>
   </para>
  </refsect2>
  <refsect2 id="{@id optionalattributes}">
   <title>Handling Optional Attributes - $options['query']['options']['attributes']</title>
   <para>
    In an LDAP directory an entry does not have to use all attributes that are
    provided by the entry's objectClass. In the following example the attributes
    'mail' and 'mobile' (among others) are missing from the first entry.
    <![CDATA[
dn: cn=Jane Doe,ou=people,dc=example,dc=com
cn: Jane Doe
objectClass: inetOrgPerson

dn: cn=John Doe,ou=people,dc=example,dc=com
cn: John Doe
mail: john.doe@example.com
mobile: 555-666-777
objectClass: inetOrgPerson
    ]]>
    This would potentially lead to problems
    as it is contrary to what is possible in a RDBMS, where every record has to have a value for each
    column (even if it's NULL). XML_Query2XML was primarily built with an RDBMS in mind and therefore
    expects all data returned by a driver to be records represented as an array of associative arrays
    (where each associative array uses the same keys).
   </para>
   <para>
    To solve this problem the columns corresponding
    to missing attributes have to be set to null. But to tell the LDAP driver which columns to check for, you
    have to use the $options['query']['options']['attributes']. (Note: $options['query'] is
    an alias for $options['sql'])
   </para>
   <para>
    $options['query']['options']['attributes'] will be used by Net_LDAP to limit the
    attributes returned for each record (see the
    {@link http://pear.php.net/manual/en/package.networking.net-ldap.search.php Net_LDAP manual}).
    In addition to this, XML_Query2XML's LDAP driver will look at this option to
    determine which columns to set to null if they do not exist in the returned records.
   </para>
   <para>
    Let's look at what happens if you do not specify the 'attributes' option:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'Net/LDAP.php';

/*
* just pass an instance of Net_LDAP to the factory method
* as you would do it with an MDB2 or PDO instance.
*/
$query2xml = XML_Query2XML::factory(Net_LDAP::connect());

$dom = $query2xml->getXML(
    array(
        'base' => 'ou=people,dc=example,dc=com',
        'filter' => '(objectclass=inetOrgPerson)'
        //we completely omit 'options' here
    ),
    array(
        'rootTag' => 'employees',
        'idColumn' => 'cn',
        'rowTag' => 'employee',
        'elements' => array(
            'cn',
            'pager'
        )
    )
);
header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    You would get something like this:
    <![CDATA[
Fatal error: Uncaught XML_Query2XML_ConfigException: [elements][pager]: The column "pager" was not found in the result set.
    ]]>
    This is because Jane Doe does not have a pager. As the LDAP driver was not told
    that the 'pager' attribute might be missing from some entries, it returned Jane
    Doe's record without the column 'pager'.
    An LDAP query specification should therefore always use the 'attributes' option!
   </para>
  </refsect2>
  <refsect2 id="{@id multivalueattributes}">
   <title>Handling Multi-Value Attributes</title>
   <para>
    In an LDAP directory, attributes are mutli-valued, that is they can hold multiple values.
    This is nice because it allows you to easily store, say not just one email
    address, but as many as you like. This is contrary to what you can usually
    do in an RDBMS. As XML_Query2XML was built primarily with an RDBMS in mind,
    it expects simple records, each represented by a one-dimensional array to be
    returned by the LDAP driver.
   </para>
   <para>
    The LDAP driver therefore creates multiple records for each entry that
    has multi-value attributes. An entry like
    <![CDATA[
## LDIF entry for "John Doe"
dn: cn=John Doe,ou=people,dc=example,dc=com
cn: John Doe
sn: Doe
mail: john@example.com
mail: johndoe@example.com
mail: john.doe@example.com
telephoneNumber: 555-111-222
telephoneNumber: 555-222-333
mobile: 666-777-888
    ]]>
    therefore has to be converted into multiple one-dimensional associative
    arrays (i.e. records):
    <![CDATA[
    cn        mail                  telephoneNumber  mobile
    -------------------------------------------------------
    John Doe  john@example.com      555-111-222      666-777-888
    John Doe  johndoe@example.com   555-222-333      666-777-888
    John Doe  john.doe@example.com  555-111-222      666-777-888
    ]]>
    Note that no cartasian product of the mail-values and the mobile-values
    is produced (that would result in six instead of three records in the
    above example). The number of records returned is equal to the number
    values assigned to the attribute that has the most values (here
    it's the mail attribute that has 3 values). To make sure that every
    record has valid values for all attributes/columns, we continiusly loop
    over the available value until the attribute with the most values
    is done. In the above example the attribute telephoneNumber had only
    two values while the mail attribute had three. The record for
    the third mail attribute value therefore contains the first value of
    the telephoneNumber attribute.
   </para>
   <para>
    So what does that mean for $options (the second argument passed to getXML())?
    It means that not much changes compared to how you would define $options
    when using a database-related driver. As shown above, using
    {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.simple_element_specifications}
    will work, but will only produce the first value for each attribute:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'Net/LDAP.php';

$query2xml = XML_Query2XML::factory(Net_LDAP::connect());

$dom = $query2xml->getXML(
    array(
        'base' => 'ou=people,dc=example,dc=com',
        'filter' => '(objectclass=inetOrgPerson)',
        'options' => array(
            'attributes' => array( //to tell the LDAP driver which columns to watch out for
                'cn',
                'mail',
            )
        )
    ),
    array(
        'rootTag' => 'employees',
        'idColumn' => 'cn',
        'rowTag' => 'employee',
        'elements' => array(
            'cn',     //simple element specification
            'mail'    //simple element specification
        )
    )
);
header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    notice how the resulting XML only shows the first value of the mail attribute:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<employees>
  <employee>
    <cn>John Doe</cn>
    <mail>john@example.com</mail>
  </employee>
  <employee>
    <cn>Jane Doe</cn>
    <mail>jane@example.com</mail>
  </employee>
</employees>
    ]]>
    </programlisting>
    To get a "mail" XML element for each value of the "mail" LDAP attribute, we have
    to use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}
    and set {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn}:
    <programlisting role="php">
    <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'Net/LDAP.php';

$query2xml = XML_Query2XML::factory(Net_LDAP::connect());

$dom = $query2xml->getXML(
    array(
        'base' => 'ou=people,dc=example,dc=com',
        'filter' => '(objectclass=inetOrgPerson)',
        'options' => array(
            'attributes' => array( //to tell the LDAP driver which columns to watch out for
                'cn',
                'mail',
            )
        )
    ),
    array(
        'rootTag' => 'employees',
        'idColumn' => 'cn',
        'rowTag' => 'employee',
        'elements' => array(
            'cn',     //simple element specification
            'mail' => array(
                'idColumn' => 'mail',
                'value' => 'mail'
            )
        )
    )
);
header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    This produces the following XML data:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<employees>
  <employee>
    <cn>John Doe</cn>
    <mail>john@example.com</mail>
    <mail>johndoe@example.com</mail>
    <mail>john.doe@example.com</mail>
  </employee>
  <employee>
    <cn>Jane Doe</cn>
    <mail>jane@example.com</mail>
    <mail>jane.doe@example.com</mail>
  </employee>
</employees>
    ]]>
    </programlisting>
    This is because we set {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn}
    within the complex element specification to "mail". Every record with a unique value
    for the column "mail" is therefore processed.
   </para>
   <para>
    As all LDAP attributes can have multiple values it is therefore highly recommended to
    always use a complex element specification with $options['idColumn'] as described above.
    The only exception is when you just want a single value (and don't care which one).
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="{@id multipledrivers}">
  <title>Using Multiple Drivers</title>
  <para>
   There might be a situation where you want to genearte your XML data from multiple RDBMSes or
   an RDBMS and an LDAP server. By using the option 'driver' within a
   {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification} or a
   {@tutorial XML_Query2XML.pkg#ldap.queryspecification} you can specify any driver you want.
   To create an instance of one of the drivers that come with XML_Query2XML use
   {@link XML_Query2XML_Driver::factory()}. If you want to write your own driver, please see
   {@tutorial XML_Query2XML.pkg#yourdriver}. Let's start with an example that pulls data
   from a MySQL and a ProstgreSQL database:
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';

$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

$pgsqlDriver = XML_Query2XML_Driver::factory(MDB2::factory('pgsql://postgres:test@localhost/query2xml_tests'));
$dom = $query2xml->getXML(
    'SELECT * FROM artist',
    array(
        'rootTag' => 'artists',
        'idColumn' => 'artistid',
        'rowTag' => 'artist',
        'elements' => array(
            'name',
            'genre',
            'album' => array(
                'sql' => array(
                    'driver' => $pgsqlDriver,
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'idColumn' => 'albumid',
                'elements' => array(
                    'title',
                    'published_year'
                )
            )
        )
    )
);
header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
    ]]>
    </programlisting>
    The resulting XML being:
    <programlisting role="tutorial">
    <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<artists>
  <artist>
    <name>Curtis Mayfield</name>
    <genre>Soul</genre>
    <album>
      <title>New World Order</title>
      <published_year>1990</published_year>
    </album>
    <album>
      <title>Curtis</title>
      <published_year>1970</published_year>
    </album>
  </artist>
  <artist>
    <name>Isaac Hayes</name>
    <genre>Soul</genre>
    <album>
      <title>Shaft</title>
      <published_year>1972</published_year>
    </album>
  </artist>
  <artist>
    <name>Ray Charles</name>
    <genre>Country and Soul</genre>
  </artist>
</artists>
    ]]>
    </programlisting>
  </para>
  <para>
   Now let's combine an RDBMS with the data from an LDAP server:
   <programlisting role="php">
   <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'Net/LDAP.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

$dom = $query2xml->getXML(
  "SELECT * FROM employee",
  array(
    'rootTag' => 'employees',
    'idColumn' => 'employeeid',
    'rowTag' => 'employee',
    'elements' => array(
        'name' => 'employeename',
        'contact_details' => array(
            'query' => array(
                'driver' => XML_Query2XML_Driver::factory(Net_LDAP::connect()),
                'data' => array(
                    'employeename'
                ),
                'base' => 'ou=people,dc=example,dc=com',
                'filter' => '(&(objectclass=inetOrgPerson)(cn=?))',
                'options' => array(
                    'attributes' => array(
                        'cn',
                        'telephoneNumber',
                        'mobile',
                        'mail',
                        'labeledURI'
                    )
                )
            ),
            'idColumn' => 'cn',
            'elements' => array(
                'telephoneNumber' => array(
                    'idColumn' => 'telephoneNumber',
                    'value' => 'telephoneNumber'
                ),
                'mobile' => array(
                    'idColumn' => 'mobile',
                    'value' => 'mobile'
                ),
                'mail' => array(
                    'idColumn' => 'mail',
                    'value' => 'mail'
                ),
                'labeledURI' => array(
                    'idColumn' => 'labeledURI',
                    'value' => 'labeledURI'
                )
            )
        )
    ),
  )
);
$dom->formatOutput = true;
print $dom->saveXML();
?>
   ]]>
   </programlisting>
   As we only have corresponsing entries in the LDAP directory for two of our
   employees in the mysql database the resulting XML looks like this:
   <programlisting role="tutorial">
   <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<employees>
  <employee>
    <name>Michael Jones</name>
  </employee>
  <employee>
    <name>Susi Weintraub</name>
    <contact_details>
      <telephoneNumber>555-111-222</telephoneNumber>
      <mobile>555-666-777</mobile>
      <mobile>555-777-888</mobile>
      <mail>susi@example.com</mail>
      <labeledURI>http://susi.example.com</labeledURI>
      <labeledURI>http://susiweintraub.example.com</labeledURI>
      <labeledURI>http://susi.weintraub.example.com</labeledURI>
    </contact_details>
  </employee>
  <employee>
    <name>Steve Hack</name>
  </employee>
  <employee>
    <name>Joan Kerr</name>
  </employee>
  <employee>
    <name>Marcus Roth</name>
  </employee>
  <employee>
    <name>Jack Mack</name>
  </employee>
  <employee>
    <name>Rita Doktor</name>
  </employee>
  <employee>
    <name>David Til</name>
  </employee>
  <employee>
    <name>Pia Eist</name>
  </employee>
  <employee>
    <name>Hanna Poll</name>
  </employee>
  <employee>
    <name>Jim Wells</name>
    <contact_details>
      <telephoneNumber>555-444-888</telephoneNumber>
      <mobile>555-666-777</mobile>
      <mail>jim@example.com</mail>
      <mail>jim.wells@example.com</mail>
      <mail>jimwells@example.com</mail>
      <mail>jwells@example.com</mail>
      <labeledURI>http://jimwells.example.com</labeledURI>
      <labeledURI>http://jim.wells.example.com</labeledURI>
    </contact_details>
  </employee>
  <employee>
    <name>Sandra Wilson</name>
  </employee>
</employees>
   ]]>
   </programlisting>
  </para>
 </refsect1>

 <refsect1 id="{@id x_to_n}">
  <title>Implementing 1:N and N:N relationships</title>
  <para>
   Often times you will have a one-to-many (1:N) or many-to-many (N:N) relationship between
   two tables. For example, the
   {@link http://query2xml.sourceforge.net/docs/Query2XML_Tests.jpg ER diagram}
   of our sample applications shows an 1:N relationship between the tables artist and album
   (<emphasis>one</emphasis> artist can perform <emphasis>many</emphasis> albums). For
   the sake of simplicity we will be using this 1:N relationship in this section (note that
   the intersection table employee_department implements an N:N relationship between employee
   and department).
  </para>
  <para>
   When dealing with 1:N or N:N relationships there are two basic questions that determine
   how you will use XML_Query2XML to implement your solution:
   <itemizedlist>
  	<listitem>
  	 Do you want to use {@tutorial XML_Query2XML.pkg#x_to_n.one_or_many_queries}
  	</listitem>
  	<listitem>
  	 Do you want to produce {@tutorial XML_Query2XML.pkg#x_to_n.one_or_many_elements}
  	</listitem>
   </itemizedlist>
  </para>
  <refsect2 id="{@id one_or_many_queries}">
   <title>One or Many Queries?</title>
   <para>
    In almost every situation you will be better of using one big query than running
    multiple smaller queries. Anyway, XML_Query2XML gives you the option of
    <itemizedlist>
  	 <listitem>
  	  {@tutorial XML_Query2XML.pkg#x_to_n.one_or_many_queries.join} (one query)
  	 </listitem>
  	 <listitem>
  	  {@tutorial XML_Query2XML.pkg#x_to_n.one_or_many_queries.options_sql} (multiple queries)
  	 </listitem>
    </itemizedlist>
   </para>
   <refsect3 id="{@id join}">
    <title>Using an SQL JOIN</title>
    <para>
     The best way to query two tables is to JOIN them together using an SQL JOIN.
     If you are new to SQL check out first what wikipedia has to say about {@link http://en.wikipedia.org/wiki/Join_(SQL) Joins}.
     I could also recommend
     {@link http://www.amazon.com/Learning-SQL-Alan-Beaulieu/dp/0596007272/ref=pd_bbs_sr_1?ie=UTF8&amp;s=books&amp;qid=1206554386&amp;sr=1-1 Learning SQL}
     by Alan Beaulieu.
    </para>
    <para>
     Use {@link XML_Query2XML::getXML()}'s first argument {@tutorial XML_Query2XML.pkg#query2xml_getxml.sql}
     to pass the SQL JOIN to XML_Query2XML.
    </para>
    <para>
     A very important thing to keep in mind is the correct specification of
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn}. On
     the root level it is set to 'artistid' (the parent entity's primary key) while
     on the level of $options['elements']['albums'] it is set to 'albumid'
     (the child entity's primary key). Here goes the code:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    'SELECT
        *
     FROM
        artist, album
     WHERE
        album.artist_id = artist.artistid',
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title'
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     And the resulting XML data looks as follows:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <albums>
      <album>
        <albumid>1</albumid>
        <title>New World Order</title>
      </album>
      <album>
        <albumid>2</albumid>
        <title>Curtis</title>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <albums>
      <album>
        <albumid>3</albumid>
        <title>Shaft</title>
      </album>
    </albums>
  </artist>
</music_library>
     ]]>
     </programlisting>
     Note: as we used a traditional join (and therefore implecitely an INNER JOIN) only those
     artists are included that also have albums in our database. To also get those artists
     that don't have any albums we would have to use a LEFT OUTER JOIN.
    </para>
   </refsect3>
   <refsect3 id="{@id options_sql}">
    <title>Using $options['sql']</title>
    <para>
     If for whatever reason you cannot join the two tables, you can use
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql} to specify
     a separate query for the second table. This will however result in the
     second query being executed as many times as the there are records in
     the first table. It is therefore highly recommended to use a JOIN
     whenever possible.
    </para>
    <para>
     To produce a similar XML as with the JOIN above we have to use a
     {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification}
     with artist.artistid for $options['elements']['albums']['sql']['data'] and
     'SELECT * FROM album WHERE artist_id = ?' for $options['elements']['albums']['sql']['query']:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    'SELECT * FROM artist',
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'elements' => array(
                    'albumid',
                    'title'
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     Note that $options['elements']['albums']['idColumn'] is again set to 'albumid'.
    </para>
    <para>
     The difference to the above XML is that it also includes artists that have no albums in our database.
     This is because using two separate queries is like using an OUTER JOIN while in the above
     example we were using an INNER JOIN.
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <albums>
      <album>
        <albumid>1</albumid>
        <title>New World Order</title>
      </album>
      <album>
        <albumid>2</albumid>
        <title>Curtis</title>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <albums>
      <album>
        <albumid>3</albumid>
        <title>Shaft</title>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <albums/>
  </artist>
</music_library>
     ]]>
     </programlisting>
    </para>
   </refsect3>
  </refsect2>
  <refsect2 id="{@id one_or_many_elements}">
   <title>One or Many Elements Per Related Entity?</title>
   <para>
    Depending on whether you want one or multiple XML element per related entity,
    you have two options here:
    <itemizedlist>
  	 <listitem>
      {@tutorial XML_Query2XML.pkg#x_to_n.one_or_many_elements.options_elements}.
     </listitem>
     <listitem>
      {@tutorial XML_Query2XML.pkg#x_to_n.one_or_many_elements.options_value}.
     </listitem>
    </itemizedlist>
   </para>
   <refsect3 id="{@id options_elements}">
    <title>Multiple Elements Per Entity - $options['elements']</title>
    <para>
     In most cases you will need to create multiple XML elements for each
     related entity. In our example we might want the albumid and the title
     for each album. This means that we have to assign
     <programlisting role="php">
     <![CDATA[
array(
    'albumid',
    'title'
);
     ]]>
     </programlisting>
     to $options['elements']['albums']['elements'].
    </para>
    <para>
     Please see the {@tutorial XML_Query2XML.pkg#x_to_n.one_or_many_queries} section above
     for two example - one using a JOIN and the second using two queries.
    </para>
   </refsect3>
   <refsect3 id="{@id options_value}">
    <title>One Element Per Entity - $options['value']</title>
    <para>
     In our example, if you want just a single XML element for each album like below,
     we can use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_value}.
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <name>Curtis Mayfield</name>
    <album>New World Order</album>
    <album>Curtis</album>
  </artist>
  <artist>
    <name>Isaac Hayes</name>
    <album>Shaft</album>
  </artist>
</music_library>
     ]]>
     </programlisting>
     The code to generate the above XML would look like this:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    'SELECT
        *
     FROM
        artist, album
     WHERE
        album.artist_id = artist.artistid',
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'name',
            'album' => array(
                'idColumn' => 'albumid',
                'value' => 'title'
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     The critical part here is $options['elements']['albums']['idColumn'].
     It is set to 'albumid'. This means that an XML element will be created
     for $options['elements']['albums'] for each unique albumid.
    </para>
    <para>
     The above example uses a JOIN which is most efficient.
     But as shown above under
     {@tutorial XML_Query2XML.pkg#x_to_n.one_or_many_queries.options_sql}
     there might be situations where you want to use multiple SQL queries
     instead of a single JOIN:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    'SELECT * FROM artist',
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'name',
            'album' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'idColumn' => 'albumid',
                'value' => 'title'
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     The resulting XML is similar to the one generated above. There is just
     one difference: artists that have no albums are included as well:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <name>Curtis Mayfield</name>
    <album>New World Order</album>
    <album>Curtis</album>
  </artist>
  <artist>
    <name>Isaac Hayes</name>
    <album>Shaft</album>
  </artist>
  <artist>
    <name>Ray Charles</name>
  </artist>
</music_library>
     ]]>
     </programlisting>
    </para>
   </refsect3>
  </refsect2>
  <refsect2 id="{@id joins}">
   <title>A last word on JOINs</title>
   <para>
    As a general rule, it is wise to use as few SQL queries as possible.
    This means that you have to JOIN you tables. It is essential to understand
    the differences between INNER and OUTER joins and how they affect your
    result set.
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="{@id yourdriver}">
  <title>Writing Your Own Driver</title>
  <para>
   If you want to work with a primary data source other than
   PDO, MDB2, DB, ADOdb or Net_LDAP, you might want to write
   your own driver.
  </para>
  <para>
   Start out by extending the abstract class
   {@link XML_Query2XML_Driver} and implementing its abstract method
   getAllRecords():
   <programlisting role="php">
   <![CDATA[
/**Contains the abstract class XML_Query2XML_Driver and the
* exception class XML_Query2XML_DBException.
*/
require_once 'XML/Query2XML.php';

class MyFirebirdDriver extends XML_Query2XML_Driver
{
    /*This method is defined as an abstract method within
    * XML_Query2XML_Driver and therefore has to be implemented.
    */
    public function getAllRecords($sql, $configPath)
    {
    }
}
?>
   ]]>
   </programlisting>
   For the sake of example, we'll be building a Firebird driver using
   PHP's native interbase API.
  </para>
  <para>
   Now let's add a constructor method that accepts the arguments needed to
   set up an Interbase/Firebird connection:
   <programlisting role="php">
   <![CDATA[
<?php
public function __construct($database, $username, $password)
{
    $this->_dbh = @ibase_pconnect($database, $username, $password);
    if ($this->_dbh === false) {
        throw new XML_Query2XML_DBException(
            'Could not connect to database: ' . ibase_errmsg()
            . '(error code: ' . ibase_errcode() . ')'
        );
    }
}
?>
   ]]>
   </programlisting>
  </para>
  <para>
   Before we code the body of our getAllRecords() method, we have to
   decide whether to overwrite the method {@link XML_Query2XML_Driver::preprocessQuery()}.
   This method does two things:
   <itemizedlist>
  	<listitem>
  	 pre-process {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}
  	</listitem>
  	<listitem>
  	 return the query statement as a string that will be used by XML_Query2XML
  	 for logging, profiling and caching
  	</listitem>
   </itemizedlist>
   The importance of preprocessQuery() lies in the fact that it determines
   the format of {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}.
   As implemented in XML_Query2XML_Driver $options['sql'] can be either
   a string or an array containing the element 'query'. If it is a string
   it will be transformed to an array with the element 'query' holding
   the string. This means that getAllRecords() only needs to deal with
   a first argument that is a string and has a 'query' element. In this
   example we will not overwrite preprocessQuery().
  </para>
  <para>
   One aspect that is not controlled by preprocessQuery() is $options['sql']['data'].
   If it is set, XML_Query2XML requires it to be an array of strings or instances of
   classes that implement XML_Query2XML_Callback. The evaluations of the specifications
   in $options['sql']['data'] are entirely handled by XML_Query2XML.
  </para>
  <para>
   All that is left now is writing the body of the getAllRecords() method.
   Regarding its first argument, {@link XML_Query2XML_Driver::preprocessQuery()} enforces the following rules
   <itemizedlist>
  	<listitem>
  	 It will be an associative array.
  	</listitem>
  	<listitem>
  	 The array will have a key named 'query'.
  	</listitem>
   </itemizedlist>
  </para>
  <para>
   A first version of getAllRecords() might therefore look like this:
   <programlisting role="php">
   <![CDATA[
<?php
public function getAllRecords($sql, $configPath)
{
    if (!isset($sql['data'])) {
        //do not presume that $sql['data'] is present
        $sql['data'] = array();
    }

    //prepare
    $statement = @ibase_prepare($this->_dbh, $sql['query']);

    //execute
    $args = $sql['data'];
    array_unshift($args, $statement);
    $result = call_user_func_array('ibase_execute', $args);

    //fetch all records
    while ($record = ibase_fetch_assoc($result, IBASE_TEXT)) {
        $records[] = $record;
    }
    ibase_free_result($result);

    return $records;
}
?>
   ]]>
   </programlisting>
   The above code is already functional but is still missings some important
   error checking. Below is the final version of our MyFirebirdDriver class,
   that includes a more robust version of getAllRecords(). Note how getAllRecords()'s
   second argument, $configPath is used for the exception messages.
   <programlisting role="php">
   <![CDATA[
<?php
/**Contains the abstract class XML_Query2XML_Driver and the
* exception class XML_Query2XML_DBException.
*/
require 'XML/Query2XML.php';
class MyFirebirdDriver extends XML_Query2XML_Driver
{
    private $_dhb = null;

    public function __construct($database, $username, $password)
    {
        $this->_dbh = @ibase_pconnect($database, $username, $password);
        if ($this->_dbh === false) {
            throw new XML_Query2XML_DBException(
                'Could not connect to database: ' . ibase_errmsg()
                . '(error code: ' . ibase_errcode() . ')'
            );
        }
    }

    /**Returns are records retrieved by running an SQL query.
    * @param mixed $sql A query string or an array with the elements
    *                   'query' (and optionally 'data').
    * @param string $configPath Where in $options the query was defined.
    * @return array All records as a two-dimensional array.
    */
    public function &getAllRecords($sql, $configPath)
    {
        if (!isset($sql['data'])) {
            //do not presume that $sql['data'] is present
            $sql['data'] = array();
        }

        /*
        * prepare
        */
        $statement = @ibase_prepare($this->_dbh, $sql['query']);
        if ($statement === false) {
            throw new XML_Query2XML_DBException(
                /*
                * Note how we use $configPath here. This will make
                * the exception message tell you where in $options
                * the error needs to be fixed.
                */
                $configPath . ': Could not prepare query "' . $sql['query'] . '": '
                . ibase_errmsg() . '(error code: ' . ibase_errcode() . ')'
            );
        }

        /*
        * execute
        */
        $args = $sql['data'];
        array_unshift($args, $statement);
        $result = call_user_func_array(
            'ibase_execute',
            $args
        );
        if ($result === false) {
            throw new XML_Query2XML_DBException(
                /*
                * Note again how we use $configPath here.
                */
                $configPath . ': Could not execute query: "' . $sql['query'] . '": '
                . ibase_errmsg() . '(error code: ' . ibase_errcode() . ')'
            );
        } elseif ($result === true) {
            //empty result set
            $records = array();
        } else {
            //fetch all records
            while ($record = ibase_fetch_assoc($result, IBASE_TEXT)) {
                $records[] = $record;
            }
            ibase_free_result($result);
        }

        /*
        * return a two dimensional array: numeric indexes in the first
        * and associative arrays in the second dimension
        */
        return $records;
    }
}

//test the driver directly
$driver = new MyFirebirdDriver('localhost:/tmp/test.fdb', 'SYSDBA', 'test');
$records = $driver->getAllRecords(
    array(
        'data' => array(1),
        'query' => 'SELECT * FROM test WHERE id = ?'
    ),
    '[config]'
);
print_r($records);
?>
   ]]>
   </programlisting>
  </para>
  <para>
   Using XML_Query2XML_DBException for a database-related driver makes sense of course.
   But when your driver has nothing to do with an RDBMS, it is recommended to create
   your own exception class by extending {@link XML_Query2XML_DriverException}:
<programlisting role="php">
   <![CDATA[
<?php
/**Exception for MyDriver errors
*/
class MyDriverException extends XML_Query2XML_DriverException
{
    /**Constructor
    * @param string $message The error message.
    */
    public function __construct($message)
    {
        parent::__construct($message);
    }
}
?>
   ]]>
   </programlisting>
   Note: it is in no way required but I would recommend that
   all exceptions your driver throws extend {@link XML_Query2XML_DriverException}. That way
   you can catch driver related exceptions in a consistent way - no matter what driver is used.
  </para>
 </refsect1>

 <refsect1 id="{@id casestudies}">
  <title>Case Studies</title>
  <para>
  	Now let's have a look at some of XML_Query2XML's features in action. We'll start out with simple cases.
  	We'll turn to rather complex ones as we proceed. All cases are included in the source distribution.
  	Each case has its own directory cases/caseXX and will consist of 5 files (Case 01 contains only
  	the first 2):
  	<itemizedlist>
  	 <listitem>
  	  <emphasis>caseXX.php</emphasis>: generates the XML data.
  	 </listitem>
  	 <listitem>
  	  <emphasis>caseXX.xml</emphasis>: the generated the XML data saved to a file.
  	 </listitem>
  	 <listitem>
  	  <emphasis>caseXX_debug.php</emphasis>: does debugging and profiling and generates
  	  caseXX.log and caseXX.profile.
  	 </listitem>
  	 <listitem>
  	  <emphasis>caseXX.log</emphasis>: the generated debug log
  	 </listitem>
  	 <listitem>
  	  <emphasis>caseXX.profile</emphasis>: the generated profile
  	 </listitem>
  	</itemizedlist>
  </para>
  <para>
   The SQL DDL used in all cases can be found in tests/Query2XML_Tests.sql and
   {@tutorial XML_Query2XML.pkg#sqlddl}.
  </para>
  <refsect2 id="{@id case01}">
    <title>Case 01: simple SELECT with getFlatXML</title>
    <para>
     Case 01 will teach you:
     <itemizedlist>
      <listitem>
       How to use {@link XML_Query2XML::getFlatXML()}.
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Case 01 is as simple as it can get. We use {@link XML_Query2XML::getFlatXML()} to generate
     flat XML data.
    </para>

    <refsect3 id="{@id case01_php}">
     <title>case01.php</title>
     <para>
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getFlatXML(
    "SELECT
        *
     FROM
        artist",
    'music_library',
    'artist');

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id case01_xml}">
     <title>case01.xml</title>
     <para>
     The result looks like this:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
  </artist>
</music_library>
     ]]>
     </programlisting>
     </para>
    </refsect3>
   </refsect2>

   <refsect2 id="{@id case02}">
    <title>Case 02: LEFT OUTER JOIN</title>
    <para>
     Case 02 will teach you:
     <itemizedlist>
      <listitem>
       The basics of {@link XML_Query2XML::getXML()}.
      </listitem>
      <listitem>
       How to use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn}.
      </listitem>
      <listitem>
       How to use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_roottag}.
      </listitem>
      <listitem>
       How to use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_rowtag}.
      </listitem>
      <listitem>
       The basics of {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}.
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Once you have to deal with LEFT JOINs and similar "complex" SQL queries, you have to use
     {@link XML_Query2XML::getXML()}. The challenge is to get the $options array
     (getXML's second argument) right:
    </para>
    <refsect3 id="{@id case02_php}">
     <title>case02.php</title>
     <para>
     case02.php looks like this:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
      getXML's first argument is the SQL query as a string. The second is the $options array.
      Let's go through all options step by step:
      <itemizedlist>
       <listitem>
  	    <emphasis>'rootTag'</emphasis>: we use 'music_library' as the name for the root tag.
  	   </listitem>
  	   <listitem>
  	    <emphasis>'rowTag'</emphasis>: all tags on the first level will represent an artis; therefore we name it 'artis'.
  	   </listitem>
  	   <listitem>
  	    <emphasis>'idColumn'</emphasis>: we set this to 'artistid' because this is the primary key column of the table
  	    artist. At least at this point it should be clear why this option is essential: our LEFT JOIN
  	    returns something like this:
        <![CDATA[
artistid  name                birth_year  albumid album_title     album_published
-------------------------------------------------------------------------------
1          Curtis Mayfield    1920        1        New World Order  1990
1          Curtis Mayfield    1920        2        Curtis           1970
2          Isaac Hayes        1942        3        Shaft            1972
3          Ray Charles        1930        NULL     NULL             NULL
        ]]>
        As we want for every artist only a single tag we need to identify each artist by the primary
        key of the table artist. Note that there is a second record for Curtis Mayfield (related to
        the album Curtis), but we don't want something like
        <programlisting role="tutorial">
        <![CDATA[
<artist>
  <name>Curtis Mayfield</name>
  <album>
    <name>New World Order</name>
  </album>
</artist>
<artist>
  <name>Curtis Mayfield</name>
  <album>
    <name>Curits</name>
  </album>
</artist>
        ]]>
        </programlisting>
        but rather
        <programlisting role="tutorial">
        <![CDATA[
<artist>
  <name>Curtis Mayfield</name>
  <albums>
    <album>
     <name>New World Order</name>
    </album>
    <albums>
     <name>Curtis</name>
    </albums>
  </albums>
</artist>
        ]]>
        </programlisting>
        This is achieved by telling XML_Query2XML which entity to focus on (on this level): the artist, as it
        is identified by the artist table's primary key. Once XML_Query2XML get's to the second Curtis Mayfield
        record, it can tell by the artistid 1 that an XML element was already created for this artist.
  	   </listitem>
  	   <listitem>
  	    <emphasis>'elements'</emphasis>: this is a (not necessarily associative) array of child elements.
  	    <itemizedlist>
  	     <listitem>
  	      <emphasis>'artistid', 'name', 'birth_year', 'birth_place', 'genre'</emphasis>: These are simple element
  	      specifications. The column name will be used as the element name and the element will only
  	      contain the column's value.
  	     </listitem>
  	     <listitem>
  	      <emphasis>'artists'</emphasis>: here we use a complex element specification. It is an array
  	      that can have all the options that can be present on the root level.
  	      <itemizedlist>
  	       <listitem>
  	        <emphasis>'rootTag'</emphasis>: we want all albums to be contained in a singel element named
  	        'albums'.
  	       </listitem>
  	       <listitem>
  	        <emphasis>'rowTag'</emphasis>: each album should be contained in an element named 'album'.
  	       </listitem>
  	       <listitem>
  	        <emphasis>'idColumn'</emphasis>: here we have to use 'albumid' for the ID column as this
  	        is the primary key column for our albums.
  	       </listitem>
  	       <listitem>
  	        <emphasis>'elements'</emphasis>: this time, a simple element specification is all we need:
  	        'albumid', 'title', 'published_year', 'comment'
  	       </listitem>
  	      </itemizedlist>
  	     </listitem>
  	    </itemizedlist>
  	   </listitem>
  	  </itemizedlist>
     </para>
    </refsect3>
    <refsect3 id="{@id case02_xml}">
     <title>case02.xml</title>
     <para>
     The resulting XML data looks like this:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>1</albumid>
        <title>New World Order</title>
        <published_year>1990</published_year>
        <comment>the best ever!</comment>
      </album>
      <album>
        <albumid>2</albumid>
        <title>Curtis</title>
        <published_year>1970</published_year>
        <comment>that man's got somthin' to say</comment>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>3</albumid>
        <title>Shaft</title>
        <published_year>1972</published_year>
        <comment>he's the man</comment>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
    <albums />
  </artist>
</music_library>
     ]]>
     </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id case02_debug_php}">
     <title>case02_debug.php</title>
     <para>
     {@link XML_Query2XML::getXML()} allows us to debug and to profile the operation.
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

require_once 'Log.php';
$debugLogger = Log::factory('file', 'case02.log', 'Query2XML');
$query2xml->enableDebugLog($debugLogger);

$query2xml->startProfiling();


$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();

require_once 'File.php';
$fp = new File();
$fp->write('case02.profile', $query2xml->getProfile(), FILE_MODE_WRITE);
?>
     ]]>
     </programlisting>
     The lines 5-7 do the debugging, line 9 and 50-52 the profiling. This will create
     case02.log and case02.profile.
     </para>
    </refsect3>
    <refsect3 id="{@id case02_log}">
     <title>case02.log</title>
     <para>
     The format of a debug log file is documented at {@tutorial XML_Query2XML.pkg#debugging}.
     Our debug log shows that the query runs once.
     <![CDATA[
Feb 11 16:10:36 Query2XML [info] QUERY: SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid
Feb 11 16:10:36 Query2XML [info] DONE
     ]]>
     </para>
    </refsect3>
    <refsect3 id="{@id case02_profile}">
     <title>case02.profile</title>
     <para>
     Profiling is essential for performance tuning. The format of the output is documented under
     {@tutorial XML_Query2XML.pkg#profiling.getprofile}. Our profile looks like this:
     <![CDATA[
FROM_DB FROM_CACHE CACHED AVG_DURATION DURATION_SUM SQL
1       0          false  0.0056409835 0.0056409835 SELECT
        *
     FROM
        artist
        LEFT JOIN album ON album.artist_id = artist.artistid

TOTAL_DURATION: 0.06843900680542
DB_DURATION:    0.015194892883301
     ]]>
     </para>
    </refsect3>
    The value "false" in the CACHED column tells us that no caching was performed. As we can see
    in the FROM_DB column, the query ran once.
   </refsect2>

   <refsect2 id="{@id case03}">
    <title>Case 03: Two SELECTs instead of a LEFT OUTER JOIN</title>
    <para>
     Case 03 will teach you:
     <itemizedlist>
      <listitem>
       How to use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql}.
      </listitem>
      <listitem>
       Prevent SQL injection.
      </listitem>
     </itemizedlist>
    </para>
    <para>
     When your query is getting bigger and bigger (say, 6 or more JOINs) you might want to (or have
     to, if the maximum number of fields your RDBMS will return has been reached) split up the big join into multiple
     smaller joins. Here we will just do exactly the same as in
     {@tutorial XML_Query2XML.pkg#casestudies.case02}, but with two separate SELECT queries.
    </para>
    <refsect3 id="{@id case03_php}">
     <title>case03.php</title>
     <para>
     case03.php looks like this:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
      We won't go over every option as we did for {@tutorial XML_Query2XML.pkg#casestudies.case02.case02_php}.
      We will only focus on the differences. The first argument to {@link XML_Query2XML::getXML()}
      is a simple SELECT query over one table. What also changed is the complex element
      specification of 'albums'. It has a new option:
      <itemizedlist>
  	   <listitem>
  	    <emphasis>'sql'</emphasis>: ['sql']['query'] will be executed for every record retrieved with
  	    the first SELECT query. In our case, we want all albums for the current artist record.
  	    We use a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql.complexqueryspecification} here:
  	    ['sql']['data'] contains an array of values that will ultimately be passed to the database abstraction
  	    layer's execute() method. As we do not prefix 'artistid' with anything it is interpreted as a column
  	    name (of the parent record) - which is just what we want. This completely prevents SQL injection attacks.
  	   </listitem>
      </itemizedlist>
     </para>
    </refsect3>
    <refsect3 id="{@id case03_xml}">
     <title>case03.xml</title>
     <para>
     The resulting XML data looks exactly like {@tutorial XML_Query2XML.pkg#casestudies.case02.case02_xml}:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>1</albumid>
        <title>New World Order</title>
        <published_year>1990</published_year>
        <comment>the best ever!</comment>
      </album>
      <album>
        <albumid>2</albumid>
        <title>Curtis</title>
        <published_year>1970</published_year>
        <comment>that man's got somthin' to say</comment>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>3</albumid>
        <title>Shaft</title>
        <published_year>1972</published_year>
        <comment>he's the man</comment>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
    <albums />
  </artist>
</music_library>
     ]]>
     </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id case03_debug_php}">
     <title>case03_debug.php</title>
     <para>
     case03_debug.php is similar to {@tutorial XML_Query2XML.pkg#casestudies.case02.case02_debug_php}:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

require_once 'Log.php';
$debugLogger = Log::factory('file', 'case03.log', 'Query2XML');
$query2xml->enableDebugLog($debugLogger);

$query2xml->startProfiling();


$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            'artistid',
            'name',
            'birth_year',
            'birth_place',
            'genre',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    'albumid',
                    'title',
                    'published_year',
                    'comment'
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();

require_once 'File.php';
$fp = new File();
$fp->write('case03.profile', $query2xml->getProfile(), FILE_MODE_WRITE);
?>
     ]]>
     </programlisting>
     The lines 6-8 do the debugging, line 10 and 54-56 the profiling. This will create
     case03.log and case03.profile.
     </para>
    </refsect3>
    <refsect3 id="{@id case03_log}">
     <title>case03.log</title>
     <para>
     The format of a debug log file is documented at {@tutorial XML_Query2XML.pkg#debugging}.
     Our debug log now contains 4 queries:
     <![CDATA[
Apr 18 19:00:20 Query2XML [info] QUERY: SELECT
        *
     FROM
        artist
     ORDER BY
        artistid
Apr 18 19:00:20 Query2XML [info] DONE
Apr 18 19:00:20 Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:1
Apr 18 19:00:20 Query2XML [info] DONE
Apr 18 19:00:20 Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:2
Apr 18 19:00:20 Query2XML [info] DONE
Apr 18 19:00:20 Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:3
Apr 18 19:00:20 Query2XML [info] DONE
     ]]>
     </para>
     The debug log shows what we expected: the first SELECT over the artist table runs once
     and the SELECT over the album table runs three times (once for every record found in
     the artist table). As the log shows no 'CACHING' entries we also know that no cashing
     was performed ({@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.cached}
     was not set to true).
    </refsect3>
    <refsect3 id="{@id case03_profile}">
     <title>case03.profile</title>
     <para>
     Profiling is essential for performance tuning. The format of the output is documented under
     {@tutorial XML_Query2XML.pkg#profiling.getprofile}. Our profile looks like this:
     <![CDATA[
FROM_DB FROM_CACHE CACHED AVG_DURATION DURATION_SUM SQL
1       0          false  0.0030851364 0.0030851364 SELECT
        *
     FROM
        artist
3       0          false  0.0035093625 0.0105280876 SELECT * FROM album WHERE artist_id = ?

TOTAL_DURATION: 0.090610980987549
DB_DURATION:    0.024358034133911
     ]]>
     If you compare our DB_DURATION value to the one in
     {@tutorial XML_Query2XML.pkg#casestudies.case02.case02_profile} you will see that the single LEFT JOIN
     was faster than the four separate queries.
     </para>
    </refsect3>
   </refsect2>
   <refsect2 id="{@id case04}">
    <title>Case 04: Case 03 with custom tag names, attributes, merge_selective and more</title>
    <para>
     Case 04 will teach you:
     <itemizedlist>
      <listitem>
       How to use alternative tag names.
      </listitem>
      <listitem>
       How to use callbacks with the '#' prefix.
      </listitem>
      <listitem>
       How to define static node and attribute values using the ':' prefix.
      </listitem>
      <listitem>
       How to prevent the creation of a root tag, using {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_roottag}.
      </listitem>
     </itemizedlist>
    </para>
    <para>
     This is very much like {@tutorial XML_Query2XML.pkg#casestudies.case03}, but with a demonstration
     of some splecial features.
    </para>
    <para>
     In contrast to Case 03 we want:
     <itemizedlist>
      <listitem>
       all tag names should be uppercase
      </listitem>
      <listitem>
       an additional child tag for ARTIST: BIRTH_YEAR_TWO_DIGIT that will contain
       only the last two digets of BIRTH_YERAR
      </listitem>
      <listitem>
       the ARTIST tag should have two attributes: ARTISTID and MAINTAINER set to the static value
       'Lukas Feiler'.
      </listitem>
      <listitem>
       the ALBUM tags should not be contained in an ALBUMS tag but should be directly within the
       ARTIST tag, e.g.
       <programlisting role="tutorial">
       <![CDATA[
<artist>
  ...
  <album>...</album>
  <album>...</album>
</artist>
       ]]>
       </programlisting>
       instead of
       <programlisting role="tutorial">
       <![CDATA[
<artist>
  ...
  <album>
    <album>...</album>
    <album>...</album>
  </albums>
</artist>
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       the ALBUM tag should have one attribute: ALBUMID
      </listitem>
      <listitem>
       the ALBUM tag should have an additional child tag: GENRE; note that this is a column of
       the table artist!
      </listitem>
     </itemizedlist>
    </para>
    <refsect3 id="{@id case04_php}">
     <title>case04.php</title>
     <para>
     case04.php looks like this:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'MUSIC_LIBRARY',
        'rowTag' => 'ARTIST',
        'idColumn' => 'artistid',
        'elements' => array(
            'NAME' => 'name',
            'BIRTH_YEAR' => 'birth_year',
            'BIRTH_YEAR_TWO_DIGIT' => "#firstTwoChars()",
            'BIRTH_PLACE' => 'birth_place',
            'GENRE' => 'genre',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'sql_options' => array(
                    'merge_selective' => array('genre')
                ),
                'rootTag' => '',
                'rowTag' => 'ALBUM',
                'idColumn' => 'albumid',
                'elements' => array(
                    'TITLE' => 'title',
                    'PUBLISHED_YEAR' => 'published_year',
                    'COMMENT' => 'comment',
                    'GENRE' => 'genre'
                ),
                'attributes' => array(
                    'ALBUMID' => 'albumid'
                )
            )
        ),
        'attributes' => array(
            'ARTISTID' => 'artistid',
            'MAINTAINER' => ':Lukas Feiler'
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();

function firstTwoChars($record)
{
    return substr($record['birth_year'], 2);
}
?>
     ]]>
     </programlisting>
     Let's go over the changes:
     <itemizedlist>
      <listitem>
       as we wanted all tag names uppercased, all elements were specified like
       <![CDATA[
       'TAG_NAME' => 'column_name'
       ]]>
       This is because XML_Query2XML will use the array key as the tag name if it is not
       numeric.
      </listitem>
      <listitem>
       BIRTH_YEAR_TWO_DIGIT was specified as
       <![CDATA[
       'BIRTH_YEAR_TWO_DIGIT' => "#firstTwoChars()",
       ]]>
       The prefix '#' tells XML_Query2XML that the following string is a function to call.
       The current record is passed as argument to that function. firstTwoChars in our case
       returns the first two characters of the string stored in $record['birth_year'].
      </listitem>
      <listitem>
       the ARTIST tag now has two attributes: they are specified in an array using
       {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes the 'attribute' option}.
       Both use a {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes.simple_attribute_specifications}.
       The ARTISTID attribute simply uses the column name 'artistid'. In the MAINTAINER attribute
       we specify a static value. This is done by prefixing it by a colon (':'). Without the
       colon, XML_Query2XML would treat it as a column name.
      </listitem>
      <listitem>
       the ALBUM tags are now not contained in an ALBUMS tag anymore but directly within the
       ARTIST tag; this is done by setting 'rootTag' to an empty string. Alternatively we just could
       have omitted the rootTag option.
      </listitem>
      <listitem>
       ALBUM's new attribute ALBUMID is specified using
       {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_attributes the 'attribute' option}.
      </listitem>
      <listitem>
       ALBUM's new child tag GENRE contains the value of a column of the table artist.
       If we had used the sql default options we would have seen a
       XML_Query2XML_ConfigException with the following message:
       <![CDATA[
[elements][albums][elements][GENRE]: The column "genre" was not found in the result set.
       ]]>
       This is because the result of the first SQL query is not available at this level. As far as
       this level is concerned, it got
       overwritten with the result of our second query. But as we need both to be present, we
       selectively merger them using {@link http://www.php.net/array_merge array_merge()}.
       This is achieved by setting
       {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.merge_selective the sql_option 'merge_selective'}
       to an array that contains
       all columns of the parent record that should also be available on the current level.
       As we do not have any confilicting column names, we just leave
       {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.merge_master the sql_option 'merge_master'}
       set to false which means that the results of the parent level's query is the 'master', i.e. overwrite
       the results from the query on this level.
      </listitem>
     </itemizedlist>
     </para>
    </refsect3>
    <refsect3 id="{@id case04_xml}">
     <title>case04.xml</title>
     <para>
     The resulting XML data looks like this:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<MUSIC_LIBRARY>
  <ARTIST ARTISTID="1" MAINTAINER="Lukas Feiler">
    <NAME>Curtis Mayfield</NAME>
    <BIRTH_YEAR>1920</BIRTH_YEAR>
    <BIRTH_YEAR_TWO_DIGIT>20</BIRTH_YEAR_TWO_DIGIT>
    <BIRTH_PLACE>Chicago</BIRTH_PLACE>
    <GENRE>Soul</GENRE>
    <ALBUM ALBUMID="1">
      <TITLE>New World Order</TITLE>
      <PUBLISHED_YEAR>1990</PUBLISHED_YEAR>
      <COMMENT>the best ever!</COMMENT>
      <GENRE>Soul</GENRE>
    </ALBUM>
    <ALBUM ALBUMID="2">
      <TITLE>Curtis</TITLE>
      <PUBLISHED_YEAR>1970</PUBLISHED_YEAR>
      <COMMENT>that man's got somthin' to say</COMMENT>
      <GENRE>Soul</GENRE>
    </ALBUM>
  </ARTIST>
  <ARTIST ARTISTID="2" MAINTAINER="Lukas Feiler">
    <NAME>Isaac Hayes</NAME>
    <BIRTH_YEAR>1942</BIRTH_YEAR>
    <BIRTH_YEAR_TWO_DIGIT>42</BIRTH_YEAR_TWO_DIGIT>
    <BIRTH_PLACE>Tennessee</BIRTH_PLACE>
    <GENRE>Soul</GENRE>
    <ALBUM ALBUMID="3">
      <TITLE>Shaft</TITLE>
      <PUBLISHED_YEAR>1972</PUBLISHED_YEAR>
      <COMMENT>he's the man</COMMENT>
      <GENRE>Soul</GENRE>
    </ALBUM>
  </ARTIST>
  <ARTIST ARTISTID="3" MAINTAINER="Lukas Feiler">
    <NAME>Ray Charles</NAME>
    <BIRTH_YEAR>1930</BIRTH_YEAR>
    <BIRTH_YEAR_TWO_DIGIT>30</BIRTH_YEAR_TWO_DIGIT>
    <BIRTH_PLACE>Mississippi</BIRTH_PLACE>
    <GENRE>Country and Soul</GENRE>
  </ARTIST>
</MUSIC_LIBRARY>
     ]]>
     </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id case04_debug_php}">
     <title>case04_debug.php</title>
     <para>
     case04_debug.php reveals nothing new compared to
     {@tutorial XML_Query2XML.pkg#casestudies.case03.case03_debug_php} but it's included for
     completeness.
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

require_once 'Log.php';
$debugLogger = Log::factory('file', 'case04.log', 'Query2XML');
$query2xml->enableDebugLog($debugLogger);

$query2xml->startProfiling();


$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'MUSIC_LIBRARY',
        'rowTag' => 'ARTIST',
        'idColumn' => 'artistid',
        'elements' => array(
            'NAME' => 'name',
            'BIRTH_YEAR' => 'birth_year',
            'BIRTH_YEAR_TWO_DIGIT' => "#firstTwoChars()",
            'BIRTH_PLACE' => 'birth_place',
            'GENRE' => 'genre',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'sql_options' => array(
                    'merge_selective' => array('genre')
                ),
                'rootTag' => '',
                'rowTag' => 'ALBUM',
                'idColumn' => 'albumid',
                'elements' => array(
                    'TITLE' => 'title',
                    'PUBLISHED_YEAR' => 'published_year',
                    'COMMENT' => 'comment',
                    'GENRE' => 'genre'
                ),
                'attributes' => array(
                    'ALBUMID' => 'albumid'
                )
            )
        ),
        'attributes' => array(
            'ARTISTID' => 'artistid',
            'MAINTAINER' => ':Lukas Feiler'
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();

require_once 'File.php';
$fp = new File();
$fp->write('case04.profile', $query2xml->getProfile(), FILE_MODE_WRITE);

function firstTwoChars($record)
{
    return substr($record['birth_year'], 2);
}
?>
     ]]>
     </programlisting>
     The lines 6-8 do the debugging, line 10 and 64-66 the profiling. This will create
     case04.log and case04.profile.
     </para>
    </refsect3>
    <refsect3 id="{@id case04_log}">
     <title>case04.log</title>
     <para>
     The format of a debug log file is documented at {@tutorial XML_Query2XML.pkg#debugging}.
     Our debug log now contains 4 queries and is exactly the same as
     {@tutorial XML_Query2XML.pkg#casestudies.case03.case03_log}:
     <![CDATA[
Apr 18 19:01:25 Query2XML [info] QUERY: SELECT
        *
     FROM
        artist
     ORDER BY
        artistid
Apr 18 19:01:25 Query2XML [info] DONE
Apr 18 19:01:25 Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:1
Apr 18 19:01:25 Query2XML [info] DONE
Apr 18 19:01:25 Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:2
Apr 18 19:01:25 Query2XML [info] DONE
Apr 18 19:01:25 Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:3
Apr 18 19:01:25 Query2XML [info] DONE
     ]]>
     </para>
    </refsect3>
    <refsect3 id="{@id case04_profile}">
     <title>case04.profile</title>
     <para>
     Profiling is essential for performance tuning. The format of the output is documented under
     {@tutorial XML_Query2XML.pkg#profiling.getprofile}. Our profile looks exactly like
     {@tutorial XML_Query2XML.pkg#casestudies.case03.case03_profile}:
     <![CDATA[
FROM_DB FROM_CACHE CACHED AVG_DURATION DURATION_SUM SQL
1       0          false  0.0034000873 0.0034000873 SELECT
        *
     FROM
        artist
3       0          false  0.0035278797 0.0105836391 SELECT * FROM album WHERE artist_id = ?

TOTAL_DURATION: 0.081415891647339
DB_DURATION:    0.026465892791748
     ]]>
     </para>
    </refsect3>
   </refsect2>
   <refsect2 id="{@id case05}">
    <title>Case 05: three LEFT OUTER JOINs</title>
    <para>
     Case 05 will teach you:
     <itemizedlist>
      <listitem>
       How to write {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}
       that in turn contain {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}.
      </listitem>
      <listitem>
       How to use static methods for callbacks with the '#' prefix.
      </listitem>
      <listitem>
       How to modify the {@link http://www.php.net/manual/en/ref.dom.php#dom.class.domdocument DOMDocument}
       instance returned by getXML().
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Case 05 is a demonstration of complex element specifications.
    </para>
    <refsect3 id="{@id case05_php}">
     <title>case05.php</title>
     <para>
     case05.php looks like this:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
         *
     FROM
         customer c
         LEFT JOIN sale s ON c.customerid = s.customer_id
         LEFT JOIN album al ON s.album_id = al.albumid
         LEFT JOIN artist ar ON al.artist_id = ar.artistid",
    array(
        'rootTag' => 'music_store',
        'rowTag' => 'customer',
        'idColumn' => 'customerid',
        'elements' => array(
            'customerid',
            'first_name',
            'last_name',
            'email',
            'sales' => array(
                'rootTag' => 'sales',
                'rowTag' => 'sale',
                'idColumn' => 'saleid',
                'elements' => array(
                    'saleid',
                    'timestamp',
                    'date' => '#Callbacks::getFirstWord()',
                    'time' => '#Callbacks::getSecondWord()',
                    'album' => array(
                        'rootTag' => '',
                        'rowTag' => 'album',
                        'idColumn' => 'albumid',
                        'elements' => array(
                            'albumid',
                            'title',
                            'published_year',
                            'comment',
                            'artist' => array(
                                'rootTag' => '',
                                'rowTag' => 'artist',
                                'idColumn' => 'artistid',
                                'elements' => array(
                                    'artistid',
                                    'name',
                                    'birth_year',
                                    'birth_place',
                                    'genre'
                                ) //artist elements
                            ) //artist array
                        ) //album elements
                    ) //album array
                ) //sales elements
            ) //sales array
        ) //root elements
    ) //root
); //getXML method call

$root = $dom->firstChild;
$root->setAttribute('date_generated', date("Y-m-d\TH:i:s", 1124801570));

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();

class Callbacks
{
    function getFirstWord($record)
    {
        return substr($record['timestamp'], 0, strpos($record['timestamp'], ' '));
    }

    function getSecondWord($record)
    {
        return substr($record['timestamp'], strpos($record['timestamp'], ' ') + 1);
    }
}
?>
     ]]>
     </programlisting>
     ['elements']['sales']['elements']['date'] and ['time'] contain portions of the timestamp column.
     Also note that a separate call to DOMNode::setAttribute() is used to
     set the attribute date_generated in the root element.
     </para>
    </refsect3>
    <refsect3 id="{@id case05_xml}">
     <title>case05.xml</title>
     <para>
     The resulting XML data looks like this:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_store date_generated="2005-08-23T14:52:50">
  <customer>
    <customerid>1</customerid>
    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <email>jane.doe@example.com</email>
    <sales>
      <sale>
        <saleid>1</saleid>
        <timestamp>2005-05-25 16:32:00</timestamp>
        <date>2005-05-25</date>
        <time>16:32:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>11</saleid>
        <timestamp>2005-05-25 16:23:00</timestamp>
        <date>2005-05-25</date>
        <time>16:23:00</time>
        <album>
          <albumid>2</albumid>
          <title>Curtis</title>
          <published_year>1970</published_year>
          <comment>that man's got somthin' to say</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
  <customer>
    <customerid>2</customerid>
    <first_name>John</first_name>
    <last_name>Doe</last_name>
    <email>john.doe@example.com</email>
    <sales>
      <sale>
        <saleid>2</saleid>
        <timestamp>2005-06-05 12:56:00</timestamp>
        <date>2005-06-05</date>
        <time>12:56:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>16</saleid>
        <timestamp>2005-06-05 12:56:12</timestamp>
        <date>2005-06-05</date>
        <time>12:56:12</time>
        <album>
          <albumid>3</albumid>
          <title>Shaft</title>
          <published_year>1972</published_year>
          <comment>he's the man</comment>
          <artist>
            <artistid>2</artistid>
            <name>Isaac Hayes</name>
            <birth_year>1942</birth_year>
            <birth_place>Tennessee</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
  <customer>
    <customerid>3</customerid>
    <first_name>Susan</first_name>
    <last_name>Green</last_name>
    <email>susan.green@example.com</email>
    <sales>
      <sale>
        <saleid>3</saleid>
        <timestamp>2005-07-10 11:03:00</timestamp>
        <date>2005-07-10</date>
        <time>11:03:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>12</saleid>
        <timestamp>2005-07-10 11:56:00</timestamp>
        <date>2005-07-10</date>
        <time>11:56:00</time>
        <album>
          <albumid>2</albumid>
          <title>Curtis</title>
          <published_year>1970</published_year>
          <comment>that man's got somthin' to say</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
  <customer>
    <customerid>4</customerid>
    <first_name>Victoria</first_name>
    <last_name>Alt</last_name>
    <email>victory.alt@example.com</email>
    <sales>
      <sale>
        <saleid>4</saleid>
        <timestamp>2005-07-10 10:03:00</timestamp>
        <date>2005-07-10</date>
        <time>10:03:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>17</saleid>
        <timestamp>2005-07-10 10:03:32</timestamp>
        <date>2005-07-10</date>
        <time>10:03:32</time>
        <album>
          <albumid>3</albumid>
          <title>Shaft</title>
          <published_year>1972</published_year>
          <comment>he's the man</comment>
          <artist>
            <artistid>2</artistid>
            <name>Isaac Hayes</name>
            <birth_year>1942</birth_year>
            <birth_place>Tennessee</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
  <customer>
    <customerid>5</customerid>
    <first_name>Will</first_name>
    <last_name>Rippy</last_name>
    <email>will.wippy@example.com</email>
    <sales>
      <sale>
        <saleid>5</saleid>
        <timestamp>2005-07-10 13:03:00</timestamp>
        <date>2005-07-10</date>
        <time>13:03:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>13</saleid>
        <timestamp>2005-07-10 13:12:00</timestamp>
        <date>2005-07-10</date>
        <time>13:12:00</time>
        <album>
          <albumid>2</albumid>
          <title>Curtis</title>
          <published_year>1970</published_year>
          <comment>that man's got somthin' to say</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
  <customer>
    <customerid>6</customerid>
    <first_name>Tim</first_name>
    <last_name>Raw</last_name>
    <email>tim.raw@example.com</email>
    <sales>
      <sale>
        <saleid>6</saleid>
        <timestamp>2005-07-10 14:03:00</timestamp>
        <date>2005-07-10</date>
        <time>14:03:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>18</saleid>
        <timestamp>2005-07-10 14:03:52</timestamp>
        <date>2005-07-10</date>
        <time>14:03:52</time>
        <album>
          <albumid>3</albumid>
          <title>Shaft</title>
          <published_year>1972</published_year>
          <comment>he's the man</comment>
          <artist>
            <artistid>2</artistid>
            <name>Isaac Hayes</name>
            <birth_year>1942</birth_year>
            <birth_place>Tennessee</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
  <customer>
    <customerid>7</customerid>
    <first_name>Nick</first_name>
    <last_name>Fallow</last_name>
    <email>nick.fallow@example.com</email>
    <sales>
      <sale>
        <saleid>7</saleid>
        <timestamp>2005-07-10 15:03:00</timestamp>
        <date>2005-07-10</date>
        <time>15:03:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>14</saleid>
        <timestamp>2005-07-10 15:09:00</timestamp>
        <date>2005-07-10</date>
        <time>15:09:00</time>
        <album>
          <albumid>2</albumid>
          <title>Curtis</title>
          <published_year>1970</published_year>
          <comment>that man's got somthin' to say</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
  <customer>
    <customerid>8</customerid>
    <first_name>Ed</first_name>
    <last_name>Burton</last_name>
    <email>ed.burton@example.com</email>
    <sales>
      <sale>
        <saleid>8</saleid>
        <timestamp>2005-07-10 16:03:00</timestamp>
        <date>2005-07-10</date>
        <time>16:03:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>19</saleid>
        <timestamp>2005-07-10 16:03:01</timestamp>
        <date>2005-07-10</date>
        <time>16:03:01</time>
        <album>
          <albumid>3</albumid>
          <title>Shaft</title>
          <published_year>1972</published_year>
          <comment>he's the man</comment>
          <artist>
            <artistid>2</artistid>
            <name>Isaac Hayes</name>
            <birth_year>1942</birth_year>
            <birth_place>Tennessee</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
  <customer>
    <customerid>9</customerid>
    <first_name>Jack</first_name>
    <last_name>Woo</last_name>
    <email>jack.woo@example.com</email>
    <sales>
      <sale>
        <saleid>9</saleid>
        <timestamp>2005-07-10 18:03:00</timestamp>
        <date>2005-07-10</date>
        <time>18:03:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>15</saleid>
        <timestamp>2005-07-10 18:49:00</timestamp>
        <date>2005-07-10</date>
        <time>18:49:00</time>
        <album>
          <albumid>2</albumid>
          <title>Curtis</title>
          <published_year>1970</published_year>
          <comment>that man's got somthin' to say</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
  <customer>
    <customerid>10</customerid>
    <first_name>Maria</first_name>
    <last_name>Gonzales</last_name>
    <email>maria.gonzales@example.com</email>
    <sales>
      <sale>
        <saleid>10</saleid>
        <timestamp>2005-07-10 19:03:00</timestamp>
        <date>2005-07-10</date>
        <time>19:03:00</time>
        <album>
          <albumid>1</albumid>
          <title>New World Order</title>
          <published_year>1990</published_year>
          <comment>the best ever!</comment>
          <artist>
            <artistid>1</artistid>
            <name>Curtis Mayfield</name>
            <birth_year>1920</birth_year>
            <birth_place>Chicago</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
      <sale>
        <saleid>20</saleid>
        <timestamp>2005-07-10 19:03:50</timestamp>
        <date>2005-07-10</date>
        <time>19:03:50</time>
        <album>
          <albumid>3</albumid>
          <title>Shaft</title>
          <published_year>1972</published_year>
          <comment>he's the man</comment>
          <artist>
            <artistid>2</artistid>
            <name>Isaac Hayes</name>
            <birth_year>1942</birth_year>
            <birth_place>Tennessee</birth_place>
            <genre>Soul</genre>
          </artist>
        </album>
      </sale>
    </sales>
  </customer>
</music_store>
     ]]>
     </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id case05_debug_php}">
     <title>case05_debug.php</title>
     <para>
     case05_debug.php:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

require_once 'Log.php';
$debugLogger = Log::factory('file', 'case05.log', 'Query2XML');
$query2xml->enableDebugLog($debugLogger);

$query2xml->startProfiling();


$dom = $query2xml->getXML(
    "SELECT
         *
     FROM
         customer c
         LEFT JOIN sale s ON c.customerid = s.customer_id
         LEFT JOIN album al ON s.album_id = al.albumid
         LEFT JOIN artist ar ON al.artist_id = ar.artistid",
    array(
        'rootTag' => 'music_store',
        'rowTag' => 'customer',
        'idColumn' => 'customerid',
        'elements' => array(
            'customerid',
            'first_name',
            'last_name',
            'email',
            'sales' => array(
                'rootTag' => 'sales',
                'rowTag' => 'sale',
                'idColumn' => 'saleid',
                'elements' => array(
                    'saleid',
                    'timestamp',
                    'date' => '#Callbacks::getFirstWord()',
                    'time' => '#Callbacks::getSecondWord()',
                    'album' => array(
                        'rootTag' => '',
                        'rowTag' => 'album',
                        'idColumn' => 'albumid',
                        'elements' => array(
                            'albumid',
                            'title',
                            'published_year',
                            'comment',
                            'artist' => array(
                                'rootTag' => '',
                                'rowTag' => 'artist',
                                'idColumn' => 'artistid',
                                'elements' => array(
                                    'artistid',
                                    'name',
                                    'birth_year',
                                    'birth_place',
                                    'genre'
                                ) //artist elements
                            ) //artist array
                        ) //album elements
                    ) //album array
                ) //sales elements
            ) //sales array
        ) //root elements
    ) //root
); //getXML method call

$root = $dom->firstChild;
$root->setAttribute('date_generated', date("Y-m-d\TH:i:s", 1124801570));

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();

require_once 'File.php';
$fp = new File();
$fp->write('case05.profile', $query2xml->getProfile(), FILE_MODE_WRITE);

class Callbacks
{
    function getFirstWord($record)
    {
        return substr($record['timestamp'], 0, strpos($record['timestamp'], ' '));
    }

    function getSecondWord($record)
    {
        return substr($record['timestamp'], strpos($record['timestamp'], ' ') + 1);
    }
}
?>
     ]]>
     </programlisting>
     The lines 6-8 do the debugging, line 10 and 76-78 the profiling. This will create
     case05.log and case05.profile.
     </para>
    </refsect3>
    <refsect3 id="{@id case05_log}">
     <title>case05.log</title>
     <para>
     The format of a debug log file is documented at {@tutorial XML_Query2XML.pkg#debugging}.
     Our debug log now contains a single query:
     <![CDATA[
Feb 11 17:27:19 Query2XML [info] QUERY: SELECT
         *
     FROM
         customer c
         LEFT JOIN sale s ON c.customerid = s.customer_id
         LEFT JOIN album al ON s.album_id = al.albumid
         LEFT JOIN artist ar ON al.artist_id = ar.artistid
Feb 11 17:27:19 Query2XML [info] DONE
     ]]>
     </para>
    </refsect3>
    <refsect3 id="{@id case05_profile}">
     <title>case05.profile</title>
     <para>
     The format of the output is documented under
     {@tutorial XML_Query2XML.pkg#profiling.getprofile}:
     <![CDATA[
FROM_DB FROM_CACHE CACHED AVG_DURATION DURATION_SUM SQL
1       0          false  0.0074028968 0.0074028968 SELECT
         *
     FROM
         customer c
         LEFT JOIN sale s ON c.customerid = s.customer_id
         LEFT JOIN album al ON s.album_id = al.albumid
         LEFT JOIN artist ar ON al.artist_id = ar.artistid

TOTAL_DURATION: 0.22688508033752
DB_DURATION:    0.050441980361938
     ]]>
     </para>
    </refsect3>
   </refsect2>

   <refsect2 id="{@id case06}">
    <title>Case 06: BIG join over 10 tables</title>
    <para>
     Case 06 will teach you:
     <itemizedlist>
      <listitem>
       How to write nested {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.complex_element_specifications}.
      </listitem>
      <listitem>
       How to use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn} when
       things get really complex.
      </listitem>
      <listitem>
       How to use COMMAND OBJECTS implementing the {@link XML_Query2XML_Callback} interface.
      </listitem>
      <listitem>
       How to use the CONDITIONAL prefix '?' in combination with the '#' prefix.
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Case 06 demonstrates how complex things can get :) First have a look at the
     {@link http://query2xml.sourceforge.net/docs/Query2XML_Tests.jpg ER diagram}.
     It shows a company that sells records. The basic structure of the generated
     XML document is as follows:
     <itemizedlist>
      <listitem>
       for each store we want a list of all departments that are located in this store
      </listitem>
      <listitem>
       for each department we want a list of all employees that work in this department
      </listitem>
      <listitem>
       for each employee we want a list of all his sales
      </listitem>
      <listitem>
       for each sale we want to know the customer and the album sold
      </listitem>
      <listitem>
       for each album we want to know the artist that performed the music
      </listitem>
     </itemizedlist>
    </para>
    <refsect3 id="{@id case06_php}">
     <title>case06.php</title>
     <para>
     case06.php looks like this:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/Callback.php';
require_once 'MDB2.php';

/**Static class that provides validation and parsing methods for
* generating XML.
*
* It is static so that we can easyly call its methods from inside
* Query2XML using eval'd code.
*/
class Helper
{
    /**Associative array of US postal state codes*/
    public static $statePostalCodes = array(
        'ALABAMA' => 'AL', 'ALASKA' => 'AK', 'AMERICAN SAMOA' => 'AS', 'ARIZONA' => 'AZ', 'ARKANSAS' => 'AR', 'CALIFORNIA' => 'CA',
        'COLORADO' => 'CO', 'CONNECTICUT' => 'CT', 'DELAWARE' => 'DE', 'DISTRICT OF COLUMBIA' => 'DC', 'FEDERATED STATES OF MICRONESIA' => 'FM',
        'FLORIDA' => 'FL', 'GEORGIA' => 'GA', 'GUAM' => 'GU', 'HAWAII' => 'HI', 'IDAHO' => 'ID', 'ILLINOIS' => 'IL', 'INDIANA' => 'IN',
        'IOWA' => 'IA', 'KANSAS' => 'KS', 'KENTUCKY' => 'KY', 'LOUISIANA' => 'LA', 'MAINE' => 'ME', 'MARSHALL ISLANDS' => 'MH', 'MARYLAND' => 'MD',
        'MASSACHUSETTS' => 'MA', 'MICHIGAN' => 'MI', 'MINNESOTA' => 'MN', 'MISSISSIPPI' => 'MS', 'MISSOURI' => 'MO', 'MONTANA' => 'MT',
        'NEBRASKA' => 'NE', 'NEVADA' => 'NV', 'NEW HAMPSHIRE' => 'NH', 'NEW JERSEY' => 'NJ', 'NEW JESEY' => 'NJ', 'NEW MEXICO' => 'NM', 'NEW YORK' => 'NY',
        'NORTH CAROLINA' => 'NC', 'NORTH DAKOTA' => 'ND', 'NORTHERN MARIANA ISLANDS' => 'MP', 'OHIO' => 'OH', 'OKLAHOMA' => 'OK', 'OREGON' => 'OR',
        'PALAU' => 'PW', 'PENNSYLVANIA' => 'PA', 'PUERTO RICO' => 'PR', 'RHODE ISLAND' => 'RI', 'SOUTH CAROLINA' => 'SC', 'SOUTH DAKOTA' => 'SD',
        'TENNESSEE' => 'TN', 'TEXAS' => 'TX', 'UTAH' => 'UT', 'VERMONT' => 'VT', 'VIRGIN ISLANDS' => 'VI', 'VIRGINIA' => 'VA', 'WASHINGTON' => 'WA',
        'WEST VIRGINIA' => 'WV', 'WISCONSIN' => 'WI', 'WYOMING' => 'WY'
    );

    /**Translates a US state name into its two-letter postal code.
    * If the translation fails, $state is returned unchanged
    * @param $record The record
    */
    public static function getStatePostalCode($record)
    {
        $state = $record["state"];
        $s = str_replace("  ", " ", trim(strtoupper($state)));
        if (isset(self::$statePostalCodes[$s])) {
            return self::$statePostalCodes[$s];
        } else {
            return $state;
        }
    }

    function summarize($str, $limit=50, $appendString=' ...')
    {
        if (strlen($str) > $limit) {
            $str = substr($str, 0, $limit - strlen($appendString)) . $appendString;
        }
        return $str;
    }

    function summarizeComment($record, $limit)
    {
        return self::summarize($record["comment"], $limit);
    }
}

/**Command class that implements the command pattern.
* It implements the XML_Query2XML_Callback interface
* and therefore has to provide the public non-static
* method execute(array $record).
*/
class UppercaseColumnCommand implements XML_Query2XML_Callback
{
    public function __construct($columnName)
    {
        $this->_columnName = $columnName;
    }
    public function execute(array $record)
    {
        return strtoupper($record[$this->_columnName]);
    }
}

$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
         s.*,
         manager.employeeid AS manager_employeeid,
         manager.employeename AS manager_employeename,
         d.*,
         department_head.employeeid AS department_head_employeeid,
         department_head.employeename AS department_head_employeename,
         e.*,
         sa.*,
         c.*,
         al.*,
         ar.*,
         (SELECT COUNT(*) FROM sale WHERE sale.store_id = s.storeid) AS store_sales,
         (SELECT
            COUNT(*)
          FROM
            sale, employee, employee_department
          WHERE
            sale.employee_id = employee.employeeid
            AND
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_sales,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department, department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = department.departmentid
            AND
            department.store_id = s.storeid
         ) AS store_employees,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_employees
     FROM
         store s
          LEFT JOIN employee manager ON s.manager = manager.employeeid
         LEFT JOIN department d ON d.store_id = s.storeid
          LEFT JOIN employee department_head ON department_head.employeeid = d.department_head
          LEFT JOIN employee_department ed ON ed.department_id = d.departmentid
           LEFT JOIN employee e ON e.employeeid = ed.employee_id
            LEFT JOIN sale sa ON sa.employee_id = e.employeeid
             LEFT JOIN customer c ON c.customerid = sa.customer_id
             LEFT JOIN album al ON al.albumid = sa.album_id
              LEFT JOIN artist ar ON ar.artistid = al.artist_id",
    array(
        'rootTag' => 'music_company',
        'rowTag' => 'store',
        'idColumn' => 'storeid',
        'attributes' => array(
            'storeid'
        ),
        'elements' => array(
            'store_sales',
            'store_employees',
            'manager' => array(
                'idColumn' => 'manager_employeeid',
                'attributes' => array(
                    'manager_employeeid'
                ),
                'elements' => array(
                    'manager_employeename'
                )
            ),
            'address' => array(
                'elements' => array(
                    'country',
                    'state' => '#Helper::getStatePostalCode()',
                    'city' => new UppercaseColumnCommand('city'),
                    'street',
                    'phone'
                )
            ),
            'department' => array(
                'idColumn' => 'departmentid',
                'attributes' => array(
                    'departmentid'
                ),
                'elements' => array(
                    'department_sales',
                    'department_employees',
                    'departmentname',
                    'department_head' => array(
                        'idColumn' => 'department_head_employeeid',
                        'attributes' => array(
                            'department_head_employeeid'
                        ),
                        'elements' => array(
                            'department_head_employeename'
                        )
                    ),
                    'employees' => array(
                        'rootTag' => 'employees',
                        'rowTag' => 'employee',
                        'idColumn' => 'employeeid',
                        'attributes' => array(
                            'employeeid'
                        ),
                        'elements' => array(
                            'employeename',
                            'sales' => array(
                                'rootTag' => 'sales',
                                'rowTag' => 'sale',
                                'idColumn' => 'saleid',
                                'attributes' => array(
                                    'saleid'
                                ),
                                'elements' => array(
                                    'timestamp',
                                    'customer' => array(
                                        'idColumn' => 'customerid',
                                        'attributes' => array(
                                            'customerid'
                                        ),
                                        'elements' => array(
                                            'first_name',
                                            'last_name',
                                            'email'
                                        )
                                    ),
                                    'album' => array(
                                        'idColumn' => 'albumid',
                                        'attributes' => array(
                                            'albumid'
                                        ),
                                        'elements' => array(
                                            'title',
                                            'published_year',
                                            'comment' => '?#Helper::summarizeComment(12)',
                                            'artist' => array(
                                                'idColumn' => 'artistid',
                                                'attributes' => array(
                                                    'artistid'
                                                ),
                                                'elements' => array(
                                                    'name',
                                                    'birth_year',
                                                    'birth_place',
                                                    'genre'
                                                )
                                            )
                                        ) // album elements
                                    ) //album array
                                ) //sales elements
                            ) //sales array
                        ) //employees elements
                    ) //employees array
                ) //department elements
            ) // department array
        ) //root elements
    ) //root
); //getXML method call

$root = $dom->firstChild;
$root->setAttribute('date_generated', date("Y-m-d\TH:i:s", 1124801570));

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
     ]]>
     </programlisting>
    </para>
    <para>
     Note how {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn} is used at the different
     levels:
     <itemizedlist>
      <listitem>
       on the root level we want a record for each store and therefore use the primary key of the table 'store' as
       the idColumn:
       <programlisting role="php">
       <![CDATA[
'idColumn' => 'storeid',
       ]]>
       </programlisting>
      </listitem>
      <listitem>
       [elements][address] does not use {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_idcolumn}
       at all because all columns used at this level ('country',
       'state', 'city', 'street' and 'phone') are all columns of the table 'store'.
      </listitem>
      <listitem>
       on the level [elements][department] we want a record for each department (within the current store)
       and therefore use the primary key of the table 'department' as the idColumn:
       <programlisting role="php">
       <![CDATA[
'idColumn' => 'departmentid',
       ]]>
       </programlisting>
       The reason we can use department.departmentid without listing all departments underneath all stores is of course that
       our LEFT JOIN has the condition "LEFT JOIN department ON department.store_id = store.storeid".
      </listitem>
      <listitem>
       on the level [elements][department][elements][employees] we want a record for each employee (within
       the current department) and therefore use the primary key of the table 'employee' as the idColumn:
       <programlisting role="php">
       <![CDATA[
'idColumn' => 'employeeid',
       ]]>
       </programlisting>
       The reason we can use employee.employeeid without listing all employees underneath all departments is of course that
       our LEFT JOIN does the trick for us (implementing a n:n relationship via the table employee_department).
      </listitem>
      <listitem>
       on the level [elements][department][elements][employees][elements][sales] we want a record for each sale
       (perfmormed by the current employee) and therefore use the primary key of the table 'sale' as the idColumn:
       <programlisting role="php">
       <![CDATA[
'idColumn' => 'saleid',
       ]]>
       </programlisting>
       The reason we can use sale.saleid without listing all sales underneath all employees is of course that
       our LEFT JOIN has the condition "LEFT JOIN sale ON sale.employee_id = employee.employeeid".
      </listitem>
      <listitem>
       on the level [elements][department][elements][employees][elements][sales][elements][customer] we want a
       record for each customer (which was a party to the current sale) and therefore use the primary key of
       the table 'customer' as the idColumn:
       <programlisting role="php">
       <![CDATA[
'idColumn' => 'customerid',
       ]]>
       </programlisting>
       Logically speaking we are of course using the foreign key sale.employee_id, but as the equality of
       sale.employee_id and employee.employeeid is the condition for our LEFT JOIN, both are the same.
      </listitem>
      <listitem>
       on the level [elements][department][elements][employees][elements][sales][elements][album] we want a
       record for each album (which was subject to the current sale) and therefore use the primary key of
       the table 'album' as the idColumn:
       <programlisting role="php">
       <![CDATA[
'idColumn' => 'albumid',
       ]]>
       </programlisting>
       Logically speaking we are of course using the foreign key sale.album_id, but as the equality of
       sale.album_id and album.albumid is the condition for our LEFT JOIN, both are the same.
      </listitem>
      <listitem>
       on the level [elements][department][elements][employees][elements][sales][elements][album][elements][artist]
       we want a record for each artist (who permormed the current album) and therefore use the primary key of
       the table 'artist' as the idColumn:
       <programlisting role="php">
       <![CDATA[
'idColumn' => 'artistid',
       ]]>
       </programlisting>
       Logically speaking we are of course using the foreign key album.artist_id, but as the equality of
       album.artist_id and artist.artistid is the condition for our LEFT JOIN, both are the same.
      </listitem>
     </itemizedlist>
    </para>
    <para>
     We also use a static class called Helper here. Note how Helper::summarizeComment() is called with a second argument.
     The current record is always passed as first argument to the callback function. So we specify the "comment"
     element as
     <programlisting role="php">
     <![CDATA[
'comment' => '?#Helper::summarizeComment(12)',
     ]]>
     </programlisting>
     which means that the string '12' will be passed as second argument to Helper::summarizeComment().
     The CONDITIONAL prefix ? means that the comment element will only appear if the (summarized)
     comment != "".
     </para>
     <para>
      In addition to the CALLBACK FUNCTION we also use a COMMAND OBJECT. In our case it is
      an instance of the class UppercaseColumnCommand which implements the {@link XML_Query2XML_Callback}
      interface. We pass the column's name as constructor argument, so that UppercaseColumnCommand::execute()
      knows which column (i.e. which element of the $record array) to pass to strtoupper().
     </para>
    </refsect3>
    <refsect3 id="{@id case06_xml}">
     <title>case06.xml</title>
     <para>
     The resulting XML data looks like this:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_company date_generated="2005-08-23T14:52:50">
  <store storeid="1">
    <store_sales>10</store_sales>
    <store_employees>6</store_employees>
    <manager manager_employeeid="1">
      <manager_employeename>Michael Jones</manager_employeename>
    </manager>
    <address>
      <country>US</country>
      <state>NY</state>
      <city>NEW YORK</city>
      <street>Broadway &amp; 72nd Str</street>
      <phone>123 456 7890</phone>
    </address>
    <department departmentid="1">
      <department_sales>10</department_sales>
      <department_employees>3</department_employees>
      <departmentname>Sales</departmentname>
      <department_head department_head_employeeid="1">
        <department_head_employeename>Michael Jones</department_head_employeename>
      </department_head>
      <employees>
        <employee employeeid="1">
          <employeename>Michael Jones</employeename>
          <sales>
            <sale saleid="1">
              <timestamp>2005-05-25 16:32:00</timestamp>
              <customer customerid="1">
                <first_name>Jane</first_name>
                <last_name>Doe</last_name>
                <email>jane.doe@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="7">
              <timestamp>2005-07-10 15:03:00</timestamp>
              <customer customerid="7">
                <first_name>Nick</first_name>
                <last_name>Fallow</last_name>
                <email>nick.fallow@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="16">
              <timestamp>2005-06-05 12:56:12</timestamp>
              <customer customerid="2">
                <first_name>John</first_name>
                <last_name>Doe</last_name>
                <email>john.doe@example.com</email>
              </customer>
              <album albumid="3">
                <title>Shaft</title>
                <published_year>1972</published_year>
                <comment>he's the man</comment>
                <artist artistid="2">
                  <name>Isaac Hayes</name>
                  <birth_year>1942</birth_year>
                  <birth_place>Tennessee</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="19">
              <timestamp>2005-07-10 16:03:01</timestamp>
              <customer customerid="8">
                <first_name>Ed</first_name>
                <last_name>Burton</last_name>
                <email>ed.burton@example.com</email>
              </customer>
              <album albumid="3">
                <title>Shaft</title>
                <published_year>1972</published_year>
                <comment>he's the man</comment>
                <artist artistid="2">
                  <name>Isaac Hayes</name>
                  <birth_year>1942</birth_year>
                  <birth_place>Tennessee</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
          </sales>
        </employee>
        <employee employeeid="2">
          <employeename>Susi Weintraub</employeename>
          <sales>
            <sale saleid="3">
              <timestamp>2005-07-10 11:03:00</timestamp>
              <customer customerid="3">
                <first_name>Susan</first_name>
                <last_name>Green</last_name>
                <email>susan.green@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="9">
              <timestamp>2005-07-10 18:03:00</timestamp>
              <customer customerid="9">
                <first_name>Jack</first_name>
                <last_name>Woo</last_name>
                <email>jack.woo@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="17">
              <timestamp>2005-07-10 10:03:32</timestamp>
              <customer customerid="4">
                <first_name>Victoria</first_name>
                <last_name>Alt</last_name>
                <email>victory.alt@example.com</email>
              </customer>
              <album albumid="3">
                <title>Shaft</title>
                <published_year>1972</published_year>
                <comment>he's the man</comment>
                <artist artistid="2">
                  <name>Isaac Hayes</name>
                  <birth_year>1942</birth_year>
                  <birth_place>Tennessee</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="20">
              <timestamp>2005-07-10 19:03:50</timestamp>
              <customer customerid="10">
                <first_name>Maria</first_name>
                <last_name>Gonzales</last_name>
                <email>maria.gonzales@example.com</email>
              </customer>
              <album albumid="3">
                <title>Shaft</title>
                <published_year>1972</published_year>
                <comment>he's the man</comment>
                <artist artistid="2">
                  <name>Isaac Hayes</name>
                  <birth_year>1942</birth_year>
                  <birth_place>Tennessee</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
          </sales>
        </employee>
        <employee employeeid="3">
          <employeename>Steve Hack</employeename>
          <sales>
            <sale saleid="5">
              <timestamp>2005-07-10 13:03:00</timestamp>
              <customer customerid="5">
                <first_name>Will</first_name>
                <last_name>Rippy</last_name>
                <email>will.wippy@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="18">
              <timestamp>2005-07-10 14:03:52</timestamp>
              <customer customerid="6">
                <first_name>Tim</first_name>
                <last_name>Raw</last_name>
                <email>tim.raw@example.com</email>
              </customer>
              <album albumid="3">
                <title>Shaft</title>
                <published_year>1972</published_year>
                <comment>he's the man</comment>
                <artist artistid="2">
                  <name>Isaac Hayes</name>
                  <birth_year>1942</birth_year>
                  <birth_place>Tennessee</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
          </sales>
        </employee>
      </employees>
    </department>
    <department departmentid="2">
      <department_sales>0</department_sales>
      <department_employees>3</department_employees>
      <departmentname>Marketing</departmentname>
      <department_head department_head_employeeid="4">
        <department_head_employeename>Joan Kerr</department_head_employeename>
      </department_head>
      <employees>
        <employee employeeid="4">
          <employeename>Joan Kerr</employeename>
          <sales/>
        </employee>
        <employee employeeid="5">
          <employeename>Marcus Roth</employeename>
          <sales/>
        </employee>
        <employee employeeid="6">
          <employeename>Jack Mack</employeename>
          <sales/>
        </employee>
      </employees>
    </department>
  </store>
  <store storeid="2">
    <store_sales>10</store_sales>
    <store_employees>6</store_employees>
    <manager manager_employeeid="2">
      <manager_employeename>Susi Weintraub</manager_employeename>
    </manager>
    <address>
      <country>US</country>
      <state>NY</state>
      <city>LARCHMONT</city>
      <street>Palmer Ave 71</street>
      <phone>456 7890</phone>
    </address>
    <department departmentid="3">
      <department_sales>10</department_sales>
      <department_employees>3</department_employees>
      <departmentname>Sales</departmentname>
      <department_head department_head_employeeid="7">
        <department_head_employeename>Rita Doktor</department_head_employeename>
      </department_head>
      <employees>
        <employee employeeid="7">
          <employeename>Rita Doktor</employeename>
          <sales>
            <sale saleid="2">
              <timestamp>2005-06-05 12:56:00</timestamp>
              <customer customerid="2">
                <first_name>John</first_name>
                <last_name>Doe</last_name>
                <email>john.doe@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="8">
              <timestamp>2005-07-10 16:03:00</timestamp>
              <customer customerid="8">
                <first_name>Ed</first_name>
                <last_name>Burton</last_name>
                <email>ed.burton@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="11">
              <timestamp>2005-05-25 16:23:00</timestamp>
              <customer customerid="1">
                <first_name>Jane</first_name>
                <last_name>Doe</last_name>
                <email>jane.doe@example.com</email>
              </customer>
              <album albumid="2">
                <title>Curtis</title>
                <published_year>1970</published_year>
                <comment>that man ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="14">
              <timestamp>2005-07-10 15:09:00</timestamp>
              <customer customerid="7">
                <first_name>Nick</first_name>
                <last_name>Fallow</last_name>
                <email>nick.fallow@example.com</email>
              </customer>
              <album albumid="2">
                <title>Curtis</title>
                <published_year>1970</published_year>
                <comment>that man ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
          </sales>
        </employee>
        <employee employeeid="8">
          <employeename>David Til</employeename>
          <sales>
            <sale saleid="4">
              <timestamp>2005-07-10 10:03:00</timestamp>
              <customer customerid="4">
                <first_name>Victoria</first_name>
                <last_name>Alt</last_name>
                <email>victory.alt@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="10">
              <timestamp>2005-07-10 19:03:00</timestamp>
              <customer customerid="10">
                <first_name>Maria</first_name>
                <last_name>Gonzales</last_name>
                <email>maria.gonzales@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="12">
              <timestamp>2005-07-10 11:56:00</timestamp>
              <customer customerid="3">
                <first_name>Susan</first_name>
                <last_name>Green</last_name>
                <email>susan.green@example.com</email>
              </customer>
              <album albumid="2">
                <title>Curtis</title>
                <published_year>1970</published_year>
                <comment>that man ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="15">
              <timestamp>2005-07-10 18:49:00</timestamp>
              <customer customerid="9">
                <first_name>Jack</first_name>
                <last_name>Woo</last_name>
                <email>jack.woo@example.com</email>
              </customer>
              <album albumid="2">
                <title>Curtis</title>
                <published_year>1970</published_year>
                <comment>that man ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
          </sales>
        </employee>
        <employee employeeid="9">
          <employeename>Pia Eist</employeename>
          <sales>
            <sale saleid="6">
              <timestamp>2005-07-10 14:03:00</timestamp>
              <customer customerid="6">
                <first_name>Tim</first_name>
                <last_name>Raw</last_name>
                <email>tim.raw@example.com</email>
              </customer>
              <album albumid="1">
                <title>New World Order</title>
                <published_year>1990</published_year>
                <comment>the best ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
            <sale saleid="13">
              <timestamp>2005-07-10 13:12:00</timestamp>
              <customer customerid="5">
                <first_name>Will</first_name>
                <last_name>Rippy</last_name>
                <email>will.wippy@example.com</email>
              </customer>
              <album albumid="2">
                <title>Curtis</title>
                <published_year>1970</published_year>
                <comment>that man ...</comment>
                <artist artistid="1">
                  <name>Curtis Mayfield</name>
                  <birth_year>1920</birth_year>
                  <birth_place>Chicago</birth_place>
                  <genre>Soul</genre>
                </artist>
              </album>
            </sale>
          </sales>
        </employee>
      </employees>
    </department>
    <department departmentid="4">
      <department_sales>0</department_sales>
      <department_employees>3</department_employees>
      <departmentname>Marketing</departmentname>
      <department_head department_head_employeeid="10">
        <department_head_employeename>Hanna Poll</department_head_employeename>
      </department_head>
      <employees>
        <employee employeeid="10">
          <employeename>Hanna Poll</employeename>
          <sales/>
        </employee>
        <employee employeeid="11">
          <employeename>Jim Wells</employeename>
          <sales/>
        </employee>
        <employee employeeid="12">
          <employeename>Sandra Wilson</employeename>
          <sales/>
        </employee>
      </employees>
    </department>
  </store>
</music_company>
     ]]>
     </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id case06_debug_php}">
     <title>case06_debug.php</title>
     <para>
     case06_debug.php:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/Callback.php';
require_once 'MDB2.php';

/**Static class that provides validation and parsing methods for
* generating XML.
*
* It is static so that we can easyly call its methods from inside
* Query2XML using eval'd code.
*/
class Helper
{
    /**Associative array of US postal state codes*/
    public static $statePostalCodes = array(
        'ALABAMA' => 'AL', 'ALASKA' => 'AK', 'AMERICAN SAMOA' => 'AS', 'ARIZONA' => 'AZ', 'ARKANSAS' => 'AR', 'CALIFORNIA' => 'CA',
        'COLORADO' => 'CO', 'CONNECTICUT' => 'CT', 'DELAWARE' => 'DE', 'DISTRICT OF COLUMBIA' => 'DC', 'FEDERATED STATES OF MICRONESIA' => 'FM',
        'FLORIDA' => 'FL', 'GEORGIA' => 'GA', 'GUAM' => 'GU', 'HAWAII' => 'HI', 'IDAHO' => 'ID', 'ILLINOIS' => 'IL', 'INDIANA' => 'IN',
        'IOWA' => 'IA', 'KANSAS' => 'KS', 'KENTUCKY' => 'KY', 'LOUISIANA' => 'LA', 'MAINE' => 'ME', 'MARSHALL ISLANDS' => 'MH', 'MARYLAND' => 'MD',
        'MASSACHUSETTS' => 'MA', 'MICHIGAN' => 'MI', 'MINNESOTA' => 'MN', 'MISSISSIPPI' => 'MS', 'MISSOURI' => 'MO', 'MONTANA' => 'MT',
        'NEBRASKA' => 'NE', 'NEVADA' => 'NV', 'NEW HAMPSHIRE' => 'NH', 'NEW JERSEY' => 'NJ', 'NEW JESEY' => 'NJ', 'NEW MEXICO' => 'NM', 'NEW YORK' => 'NY',
        'NORTH CAROLINA' => 'NC', 'NORTH DAKOTA' => 'ND', 'NORTHERN MARIANA ISLANDS' => 'MP', 'OHIO' => 'OH', 'OKLAHOMA' => 'OK', 'OREGON' => 'OR',
        'PALAU' => 'PW', 'PENNSYLVANIA' => 'PA', 'PUERTO RICO' => 'PR', 'RHODE ISLAND' => 'RI', 'SOUTH CAROLINA' => 'SC', 'SOUTH DAKOTA' => 'SD',
        'TENNESSEE' => 'TN', 'TEXAS' => 'TX', 'UTAH' => 'UT', 'VERMONT' => 'VT', 'VIRGIN ISLANDS' => 'VI', 'VIRGINIA' => 'VA', 'WASHINGTON' => 'WA',
        'WEST VIRGINIA' => 'WV', 'WISCONSIN' => 'WI', 'WYOMING' => 'WY'
    );

    /**Translates a US state name into its two-letter postal code.
    * If the translation fails, $state is returned unchanged
    * @param $record The record
    */
    public static function getStatePostalCode($record)
    {
        $state = $record["state"];
        $s = str_replace("  ", " ", trim(strtoupper($state)));
        if (isset(self::$statePostalCodes[$s])) {
            return self::$statePostalCodes[$s];
        } else {
            return $state;
        }
    }

    function summarize($str, $limit=50, $appendString=' ...')
    {
        if (strlen($str) > $limit) {
            $str = substr($str, 0, $limit - strlen($appendString)) . $appendString;
        }
        return $str;
    }

    function summarizeComment($record, $limit)
    {
        return self::summarize($record["comment"], $limit);
    }
}

/**Command class that implements the command pattern.
* It implements the XML_Query2XML_Callback interface
* and therefore has to provide the public non-static
* method execute(array $record).
*/
class UppercaseColumnCommand implements XML_Query2XML_Callback
{
    public function __construct($columnName)
    {
        $this->_columnName = $columnName;
    }
    public function execute(array $record)
    {
        return strtoupper($record[$this->_columnName]);
    }
}

$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

require_once 'Log.php';
$debugLogger = Log::factory('file', 'case06.log', 'XML_Query2XML');
$query2xml->enableDebugLog($debugLogger);

$query2xml->startProfiling();


$dom = $query2xml->getXML(
    "SELECT
         s.*,
         manager.employeeid AS manager_employeeid,
         manager.employeename AS manager_employeename,
         d.*,
         department_head.employeeid AS department_head_employeeid,
         department_head.employeename AS department_head_employeename,
         e.*,
         sa.*,
         c.*,
         al.*,
         ar.*,
         (SELECT COUNT(*) FROM sale WHERE sale.store_id = s.storeid) AS store_sales,
         (SELECT
            COUNT(*)
          FROM
            sale, employee, employee_department
          WHERE
            sale.employee_id = employee.employeeid
            AND
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_sales,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department, department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = department.departmentid
            AND
            department.store_id = s.storeid
         ) AS store_employees,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_employees
     FROM
         store s
          LEFT JOIN employee manager ON s.manager = manager.employeeid
         LEFT JOIN department d ON d.store_id = s.storeid
          LEFT JOIN employee department_head ON department_head.employeeid = d.department_head
          LEFT JOIN employee_department ed ON ed.department_id = d.departmentid
           LEFT JOIN employee e ON e.employeeid = ed.employee_id
            LEFT JOIN sale sa ON sa.employee_id = e.employeeid
             LEFT JOIN customer c ON c.customerid = sa.customer_id
             LEFT JOIN album al ON al.albumid = sa.album_id
              LEFT JOIN artist ar ON ar.artistid = al.artist_id",
    array(
        'rootTag' => 'music_company',
        'rowTag' => 'store',
        'idColumn' => 'storeid',
        'attributes' => array(
            'storeid'
        ),
        'elements' => array(
            'store_sales',
            'store_employees',
            'manager' => array(
                'idColumn' => 'manager_employeeid',
                'attributes' => array(
                    'manager_employeeid'
                ),
                'elements' => array(
                    'manager_employeename'
                )
            ),
            'address' => array(
                'elements' => array(
                    'country',
                    'state' => '#Helper::getStatePostalCode()',
                    'city' => new UppercaseColumnCommand('city'),
                    'street',
                    'phone'
                )
            ),
            'department' => array(
                'idColumn' => 'departmentid',
                'attributes' => array(
                    'departmentid'
                ),
                'elements' => array(
                    'department_sales',
                    'department_employees',
                    'departmentname',
                    'department_head' => array(
                        'idColumn' => 'department_head_employeeid',
                        'attributes' => array(
                            'department_head_employeeid'
                        ),
                        'elements' => array(
                            'department_head_employeename'
                        )
                    ),
                    'employees' => array(
                        'rootTag' => 'employees',
                        'rowTag' => 'employee',
                        'idColumn' => 'employeeid',
                        'attributes' => array(
                            'employeeid'
                        ),
                        'elements' => array(
                            'employeename',
                            'sales' => array(
                                'rootTag' => 'sales',
                                'rowTag' => 'sale',
                                'idColumn' => 'saleid',
                                'attributes' => array(
                                    'saleid'
                                ),
                                'elements' => array(
                                    'timestamp',
                                    'customer' => array(
                                        'idColumn' => 'customerid',
                                        'attributes' => array(
                                            'customerid'
                                        ),
                                        'elements' => array(
                                            'first_name',
                                            'last_name',
                                            'email'
                                        )
                                    ),
                                    'album' => array(
                                        'idColumn' => 'albumid',
                                        'attributes' => array(
                                            'albumid'
                                        ),
                                        'elements' => array(
                                            'title',
                                            'published_year',
                                            'comment' => '?#Helper::summarizeComment(12)',
                                            'artist' => array(
                                                'idColumn' => 'artistid',
                                                'attributes' => array(
                                                    'artistid'
                                                ),
                                                'elements' => array(
                                                    'name',
                                                    'birth_year',
                                                    'birth_place',
                                                    'genre'
                                                )
                                            )
                                        ) // album elements
                                    ) //album array
                                ) //sales elements
                            ) //sales array
                        ) //employees elements
                    ) //employees array
                ) //department elements
            ) // department array
        ) //root elements
    ) //root
); //getXML method call

$root = $dom->firstChild;
$root->setAttribute('date_generated', date("Y-m-d\TH:i:s", 1124801570));

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();

require_once 'File.php';
$fp = new File();
$fp->write('case06.profile', $query2xml->getProfile(), FILE_MODE_WRITE);
?>
     ]]>
     </programlisting>
     The lines 75-77 do the debugging, line 79 and 254-256 the profiling. This will create
     case06.log and case06.profile.
     </para>
    </refsect3>
    <refsect3 id="{@id case06_log}">
     <title>case06.log</title>
     <para>
     The format of a debug log file is documented at {@tutorial XML_Query2XML.pkg#debugging}.
     Our debug log contains just a single query:
     <![CDATA[
Feb 11 17:39:46 XML_Query2XML [info] QUERY: SELECT
         s.*,
         manager.employeeid AS manager_employeeid,
         manager.employeename AS manager_employeename,
         d.*,
         department_head.employeeid AS department_head_employeeid,
         department_head.employeename AS department_head_employeename,
         e.*,
         sa.*,
         c.*,
         al.*,
         ar.*,
         (SELECT COUNT(*) FROM sale WHERE sale.store_id = s.storeid) AS store_sales,
         (SELECT
            COUNT(*)
          FROM
            sale, employee, employee_department
          WHERE
            sale.employee_id = employee.employeeid
            AND
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_sales,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department, department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = department.departmentid
            AND
            department.store_id = s.storeid
         ) AS store_employees,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_employees
     FROM
         store s
          LEFT JOIN employee manager ON s.manager = manager.employeeid
         LEFT JOIN department d ON d.store_id = s.storeid
          LEFT JOIN employee department_head ON department_head.employeeid = d.department_head
          LEFT JOIN employee_department ed ON ed.department_id = d.departmentid
           LEFT JOIN employee e ON e.employeeid = ed.employee_id
            LEFT JOIN sale sa ON sa.employee_id = e.employeeid
             LEFT JOIN customer c ON c.customerid = sa.customer_id
             LEFT JOIN album al ON al.albumid = sa.album_id
              LEFT JOIN artist ar ON ar.artistid = al.artist_id
Feb 11 17:39:46 XML_Query2XML [info] DONE
     ]]>
     </para>
    </refsect3>
    <refsect3 id="{@id case06_profile}">
     <title>case06.profile</title>
     <para>
     The format of the output is documented under
     {@tutorial XML_Query2XML.pkg#profiling.getprofile}:
     <![CDATA[
FROM_DB FROM_CACHE CACHED AVG_DURATION DURATION_SUM SQL
1       0          false  0.0172939300 0.0172939300 SELECT
         s.*,
         manager.employeeid AS manager_employeeid,
         manager.employeename AS manager_employeename,
         d.*,
         department_head.employeeid AS department_head_employeeid,
         department_head.employeename AS department_head_employeename,
         e.*,
         sa.*,
         c.*,
         al.*,
         ar.*,
         (SELECT COUNT(*) FROM sale WHERE sale.store_id = s.storeid) AS store_sales,
         (SELECT
            COUNT(*)
          FROM
            sale, employee, employee_department
          WHERE
            sale.employee_id = employee.employeeid
            AND
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_sales,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department, department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = department.departmentid
            AND
            department.store_id = s.storeid
         ) AS store_employees,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_employees
     FROM
         store s
          LEFT JOIN employee manager ON s.manager = manager.employeeid
         LEFT JOIN department d ON d.store_id = s.storeid
          LEFT JOIN employee department_head ON department_head.employeeid = d.department_head
          LEFT JOIN employee_department ed ON ed.department_id = d.departmentid
           LEFT JOIN employee e ON e.employeeid = ed.employee_id
            LEFT JOIN sale sa ON sa.employee_id = e.employeeid
             LEFT JOIN customer c ON c.customerid = sa.customer_id
             LEFT JOIN album al ON al.albumid = sa.album_id
              LEFT JOIN artist ar ON ar.artistid = al.artist_id

TOTAL_DURATION: 0.29014992713928
DB_DURATION:    0.1554069519043
     ]]>
     </para>
    </refsect3>
   </refsect2>
   <refsect2 id="{@id case07}">
    <title>Case 07: Case 03 with Asterisk Shortcuts</title>
    <para>
     Case 07 will teach you:
     <itemizedlist>
      <listitem>
       How to use the {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.asterisk_shortcut}
      </listitem>
     </itemizedlist>
    </para>
    <para>
     As documented under {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_elements.asterisk_shortcut}
     an asterisk can be used to treat all columns found in the result set the same.
    </para>
    <refsect3 id="{@id case07_php}">
     <title>case07.php</title>
     <para>
     case07.php looks like this:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            '*',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    '*',
                    'artist_id' => '?:'
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();
?>
      ]]>
      </programlisting>
       As in {@tutorial XML_Query2XML.pkg#casestudies.case03} we use two separate
       queries for the artist and the album tables. All columns of the artist
       table are child elements of the artist tags. The columns of the album
       table are all below the album tags - with one exception: the artist_id
       column is excluded as it only contains redundant information.
     </para>
    </refsect3>
    <refsect3 id="{@id case07_xml}">
     <title>case07.xml</title>
     <para>
     The resulting XML data is identical with {@tutorial XML_Query2XML.pkg#casestudies.case03.case03_xml}:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_library>
  <artist>
    <artistid>1</artistid>
    <name>Curtis Mayfield</name>
    <birth_year>1920</birth_year>
    <birth_place>Chicago</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>1</albumid>
        <title>New World Order</title>
        <published_year>1990</published_year>
        <comment>the best ever!</comment>
      </album>
      <album>
        <albumid>2</albumid>
        <title>Curtis</title>
        <published_year>1970</published_year>
        <comment>that man's got somthin' to say</comment>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>2</artistid>
    <name>Isaac Hayes</name>
    <birth_year>1942</birth_year>
    <birth_place>Tennessee</birth_place>
    <genre>Soul</genre>
    <albums>
      <album>
        <albumid>3</albumid>
        <title>Shaft</title>
        <published_year>1972</published_year>
        <comment>he's the man</comment>
      </album>
    </albums>
  </artist>
  <artist>
    <artistid>3</artistid>
    <name>Ray Charles</name>
    <birth_year>1930</birth_year>
    <birth_place>Mississippi</birth_place>
    <genre>Country and Soul</genre>
    <albums />
  </artist>
</music_library>
     ]]>
     </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id case07_debug_php}">
     <title>case07_debug.php</title>
     <para>
     case07_debug.php is very similar to {@tutorial XML_Query2XML.pkg#casestudies.case03.case03_debug_php}:
     <programlisting role="php">
     <![CDATA[
<?php
require_once 'XML/Query2XML.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

require_once 'Log.php';
$debugLogger = Log::factory('file', 'case07.log', 'Query2XML');
$query2xml->enableDebugLog($debugLogger);

$query2xml->startProfiling();


$dom = $query2xml->getXML(
    "SELECT
        *
     FROM
        artist",
    array(
        'rootTag' => 'music_library',
        'rowTag' => 'artist',
        'idColumn' => 'artistid',
        'elements' => array(
            '*',
            'albums' => array(
                'sql' => array(
                    'data' => array(
                        'artistid'
                    ),
                    'query' => 'SELECT * FROM album WHERE artist_id = ?'
                ),
                'rootTag' => 'albums',
                'rowTag' => 'album',
                'idColumn' => 'albumid',
                'elements' => array(
                    '*',
                    'artist_id' => '?:'
                )
            )
        )
    )
);

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();

require_once 'File.php';
$fp = new File();
$fp->write('case07.profile', $query2xml->getProfile(), FILE_MODE_WRITE);
?>
     ]]>
     </programlisting>
     The lines 6-8 do the debugging, line 10 and 48-50 the profiling. This will create
     case07.log and case07.profile.
     </para>
    </refsect3>
    <refsect3 id="{@id case07_log}">
     <title>case07.log</title>
     <para>
     The format of a debug log file is documented at {@tutorial XML_Query2XML.pkg#debugging}.
     Our debug log now contains 4 queries:
     <![CDATA[
Apr 18 19:02:48 Query2XML [info] QUERY: SELECT
        *
     FROM
        artist
     ORDER BY
        artistid
Apr 18 19:02:48 Query2XML [info] DONE
Apr 18 19:02:48 Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:1
Apr 18 19:02:48 Query2XML [info] DONE
Apr 18 19:02:48 Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:2
Apr 18 19:02:48 Query2XML [info] DONE
Apr 18 19:02:48 Query2XML [info] QUERY: SELECT * FROM album WHERE artist_id = ?; DATA:3
Apr 18 19:02:48 Query2XML [info] DONE
     ]]>
     </para>
     The debug log shows what we expected: the first SELECT over the artist table runs once
     and the SELECT over the album table runs three times (once for every record found in
     the artist table). As the log shows no 'CACHING' entries we also know that no cashing
     was performed ({@tutorial XML_Query2XML.pkg#query2xml_getxml.options_sql_options.cached}
     was not set to true).
    </refsect3>
    <refsect3 id="{@id case07_profile}">
     <title>case07.profile</title>
     <para>
     Profiling is essential for performance tuning. The format of the output is documented under
     {@tutorial XML_Query2XML.pkg#profiling.getprofile}. Our profile looks like this:
     <![CDATA[
FROM_DB FROM_CACHE CACHED AVG_DURATION DURATION_SUM SQL
1       0          false  0.0018889904 0.0018889904 SELECT
        *
     FROM
        artist
3       0          false  0.0021993319 0.0065979957 SELECT * FROM album WHERE artist_id = ?

TOTAL_DURATION: 0.052389144897461
DB_DURATION:    0.016173124313354
     ]]>
     </para>
    </refsect3>
   </refsect2>
   <refsect2 id="{@id case08}">
    <title>Case 08: Case 06 revisited: Making use of Mappers</title>
    <para>
     Case 08 will teach you:
     <itemizedlist>
      <listitem>
       How to do mapping of SQL identifiers to XML element names in accordenace with
       {@link http://www.sqlx.org/SQL-XML-documents/5FCD-14-XML-2004-07.pdf ISO/IEC 9075-14:2005}.
      </listitem>
      <listitem>
       How to write your own mappers.
      </listitem>
      <listitem>
       How to use different mappers at different levels.
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Make sure you are familiar with {@tutorial XML_Query2XML.pkg#casestudies.case06}
     before proceeding. Case 08 is different from Case 06 in the following aspects:
     <itemizedlist>
      <listitem>
       All tags and attributes directly related to columns of the table "store" shall be uppercase;
       we'll directly use the PHP function strtoupper() and the 'FUNCTION' syntax for this purpose.
      </listitem>
      <listitem>
       All tags and attributes directly related to columns of the table "department" shall use
       a naming convention like "oneTwoThree" instead of "one_two_three";
       we'll use Mappers::departmentMapper() and the 'CLASS::STATIC_METHOD' syntax for this purpose.
      </listitem>
      <listitem>
       All tags and attributes directly related to columns of the table "employee" shall use
       a naming convention like "OneTwoThree" instead of "one_two_three";
       we'll use Mappers::employeeMapper() and the array('CLASS', 'STATIC_METHOD') syntax for this purpose.
      </listitem>
      <listitem>
       All tags and attributes directly related to columns of the table "sale" shall use
       a naming convention like "ONETWOTHREE" instead of "one_two_three";
       we'll use the non-static Mappers::saleMapper() and the array($instance, 'METHOD') syntax for this purpose.
      </listitem>
      <listitem>
       All tags and attributes directly related to columns of the table "customer" shall use
       the column names as they are defined in the database;
       we'll set the mapper option to false for this purpose.
      </listitem>
      <listitem>
       All tags and attributes directly related to columns of the table "album" shall use
       the ISO 9075-mapper; we'll use XML_Query2XML_ISO9075Mapper::map() and the 'CLASS::STATIC_METHOD'
       syntax for this purpose.
      </listitem>
      <listitem>
       All tags and attributes directly related to columns of the table "artist" shall use
       a naming convention like "onetwothree" instead of "one_two_three";
       we'll the function mapArtist as the mapper and the 'FUNCTION' syntax.
      </listitem>
      <listitem>
       Due to the fact that SQLite prior to 3.1 does not support
       a subselect backreferencing to a field in its parent select
       (see {@link http://www.sqlite.org/cvstrac/wiki?p=UnsupportedSql}) Case 08 will not work
       with SQLite &lt; 3.1.
      </listitem>
     </itemizedlist>
     This certainly is not a very realistic scenario but it was chosen to demonstrate the
     different syntaxes for specifying a mapper function and how to use multiple
     mappers. This case also demonstrates that all XML names explicitly specified are
     not subject to any special mapping! For example the tag names "music_company" and
     "store" are left untouched because they are explicitly specified using the options
     "rootTag" and "rowTag". An other case is the tag "manager" which also stays untouched.
     This is because the array key ("manager" in this case) of a complex element specification
     is used for {@tutorial XML_Query2XML.pkg#query2xml_getxml.options_rowtag the option "rowTag"}
     per default. XML_Query2XML just does not pretend to be smart than you, the programmer. If you don't
     like the tag name "manager", use another array key for the complex element specification or
     use the "rowTag" option within the complex element specification.
    </para>
    <refsect3 id="{@id case08_php}">
     <title>case08.php</title>
     <para>
     case08.php looks like this:
     <programlisting role="php">
     <![CDATA[
<?php
class Mappers
{
    public static function departmentMapper($str)
    {
        //maps 'one_two_three' to 'oneTwoThree'
        return preg_replace("/(_)([a-z])/e", "strtoupper('\\2')", $str);
    }

    public static function employeeMapper($str)
    {
        //maps 'one_two_three' to 'OneTwoThree'
        return ucfirst(preg_replace("/(_)([a-z])/e", "strtoupper('\\2')", $str));
    }

    public function saleMapper($str)
    {
        //maps 'one_two_three' to 'ONETWOTHREE'
        return strtoupper(str_replace('_', '', $str));
    }
}

function mapArtist($str)
{
    //maps 'one_two_three' to 'onetwothree'
    return strtolower(str_replace('_', '', $str));
}

$myMappers = new Mappers();

require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/ISO9075Mapper.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));
$dom = $query2xml->getXML(
    "SELECT
         s.*,
         manager.employeeid AS manager_employeeid,
         manager.employeename AS manager_employeename,
         d.*,
         department_head.employeeid AS department_head_employeeid,
         department_head.employeename AS department_head_employeename,
         e.*,
         sa.*,
         c.*,
         al.*,
         ar.*,
         (SELECT COUNT(*) FROM sale WHERE sale.store_id = s.storeid) AS store_sales,
         (SELECT
            COUNT(*)
          FROM
            sale, employee, employee_department
          WHERE
            sale.employee_id = employee.employeeid
            AND
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_sales,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department, department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = department.departmentid
            AND
            department.store_id = s.storeid
         ) AS store_employees,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_employees
     FROM
         store s
          LEFT JOIN employee manager ON s.manager = manager.employeeid
         LEFT JOIN department d ON d.store_id = s.storeid
          LEFT JOIN employee department_head ON department_head.employeeid = d.department_head
          LEFT JOIN employee_department ed ON ed.department_id = d.departmentid
           LEFT JOIN employee e ON e.employeeid = ed.employee_id
            LEFT JOIN sale sa ON sa.employee_id = e.employeeid
             LEFT JOIN customer c ON c.customerid = sa.customer_id
             LEFT JOIN album al ON al.albumid = sa.album_id
              LEFT JOIN artist ar ON ar.artistid = al.artist_id",
    array(
        'rootTag' => 'music_company',
        'rowTag' => 'store',
        'idColumn' => 'storeid',
        'mapper' => 'strtoupper',
        'attributes' => array(
            'storeid'
        ),
        'elements' => array(
            'store_sales',
            'store_employees',
            'manager' => array(
                'idColumn' => 'manager_employeeid',
                'attributes' => array(
                    'manager_employeeid'
                ),
                'elements' => array(
                    'manager_employeename'
                )
            ),
            'address' => array(
                'elements' => array(
                    'country',
                    'state' => '#Helper::getStatePostalCode()',
                    'city',
                    'street',
                    'phone'
                )
            ),
            'department' => array(
                'idColumn' => 'departmentid',
                'mapper' => 'Mappers::departmentMapper',
                'attributes' => array(
                    'departmentid'
                ),
                'elements' => array(
                    'department_sales',
                    'department_employees',
                    'departmentname',
                    'department_head' => array(
                        'idColumn' => 'department_head_employeeid',
                        'attributes' => array(
                            'department_head_employeeid'
                        ),
                        'elements' => array(
                            'department_head_employeename'
                        )
                    ),
                    'employees' => array(
                        'rootTag' => 'employees',
                        'rowTag' => 'employee',
                        'idColumn' => 'employeeid',
                        'mapper' => array('Mappers', 'employeeMapper'),
                        'attributes' => array(
                            'employeeid'
                        ),
                        'elements' => array(
                            'employeename',
                            'sales' => array(
                                'rootTag' => 'sales',
                                'rowTag' => 'sale',
                                'idColumn' => 'saleid',
                                'mapper' => array($myMappers, 'saleMapper'),
                                'attributes' => array(
                                    'saleid'
                                ),
                                'elements' => array(
                                    'timestamp',
                                    'customer' => array(
                                        'idColumn' => 'customerid',
                                        'mapper' => false,
                                        'attributes' => array(
                                            'customerid'
                                        ),
                                        'elements' => array(
                                            'first_name',
                                            'last_name',
                                            'email'
                                        )
                                    ),
                                    'album' => array(
                                        'idColumn' => 'albumid',
                                        'mapper' => 'XML_Query2XML_ISO9075Mapper::map',
                                        'attributes' => array(
                                            'albumid'
                                        ),
                                        'elements' => array(
                                            'title',
                                            'published_year',
                                            'comment' => '?#Helper::summarizeComment(12)',
                                            'artist' => array(
                                                'idColumn' => 'artistid',
                                                'mapper' => 'mapArtist',
                                                'attributes' => array(
                                                    'artistid'
                                                ),
                                                'elements' => array(
                                                    'name',
                                                    'birth_year',
                                                    'birth_place',
                                                    'genre'
                                                )
                                            )
                                        ) // album elements
                                    ) //album array
                                ) //sales elements
                            ) //sales array
                        ) //employees elements
                    ) //employees array
                ) //department elements
            ) // department array
        ) //root elements
    ) //root
); //getXML method call

$root = $dom->firstChild;
$root->setAttribute('date_generated', date("Y-m-d\TH:i:s", 1124801570));

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();



/**Static class that provides validation and parsing methods for
* generating XML.
*
* It is static so that we can easyly call its methods from inside
* Query2XML using eval'd code.
*/
class Helper
{
    /**Associative array of US postal state codes*/
    public static $statePostalCodes = array(
        'ALABAMA' => 'AL', 'ALASKA' => 'AK', 'AMERICAN SAMOA' => 'AS', 'ARIZONA' => 'AZ', 'ARKANSAS' => 'AR', 'CALIFORNIA' => 'CA',
        'COLORADO' => 'CO', 'CONNECTICUT' => 'CT', 'DELAWARE' => 'DE', 'DISTRICT OF COLUMBIA' => 'DC', 'FEDERATED STATES OF MICRONESIA' => 'FM',
        'FLORIDA' => 'FL', 'GEORGIA' => 'GA', 'GUAM' => 'GU', 'HAWAII' => 'HI', 'IDAHO' => 'ID', 'ILLINOIS' => 'IL', 'INDIANA' => 'IN',
        'IOWA' => 'IA', 'KANSAS' => 'KS', 'KENTUCKY' => 'KY', 'LOUISIANA' => 'LA', 'MAINE' => 'ME', 'MARSHALL ISLANDS' => 'MH', 'MARYLAND' => 'MD',
        'MASSACHUSETTS' => 'MA', 'MICHIGAN' => 'MI', 'MINNESOTA' => 'MN', 'MISSISSIPPI' => 'MS', 'MISSOURI' => 'MO', 'MONTANA' => 'MT',
        'NEBRASKA' => 'NE', 'NEVADA' => 'NV', 'NEW HAMPSHIRE' => 'NH', 'NEW JERSEY' => 'NJ', 'NEW JESEY' => 'NJ', 'NEW MEXICO' => 'NM', 'NEW YORK' => 'NY',
        'NORTH CAROLINA' => 'NC', 'NORTH DAKOTA' => 'ND', 'NORTHERN MARIANA ISLANDS' => 'MP', 'OHIO' => 'OH', 'OKLAHOMA' => 'OK', 'OREGON' => 'OR',
        'PALAU' => 'PW', 'PENNSYLVANIA' => 'PA', 'PUERTO RICO' => 'PR', 'RHODE ISLAND' => 'RI', 'SOUTH CAROLINA' => 'SC', 'SOUTH DAKOTA' => 'SD',
        'TENNESSEE' => 'TN', 'TEXAS' => 'TX', 'UTAH' => 'UT', 'VERMONT' => 'VT', 'VIRGIN ISLANDS' => 'VI', 'VIRGINIA' => 'VA', 'WASHINGTON' => 'WA',
        'WEST VIRGINIA' => 'WV', 'WISCONSIN' => 'WI', 'WYOMING' => 'WY'
    );

    /**Translates a US state name into its two-letter postal code.
    * If the translation fails, $state is returned unchanged
    * @param $record The record
    */
    public static function getStatePostalCode($record)
    {
        $state = $record["state"];
        $s = str_replace("  ", " ", trim(strtoupper($state)));
        if (isset(self::$statePostalCodes[$s])) {
            return self::$statePostalCodes[$s];
        } else {
            return $state;
        }
    }

    function summarize($str, $limit=50, $appendString=' ...')
    {
        if (strlen($str) > $limit) {
            $str = substr($str, 0, $limit - strlen($appendString)) . $appendString;
        }
        return $str;
    }


    function summarizeComment($record, $limit)
    {
        return self::summarize($record["comment"], $limit);
    }
}
?>
     ]]>
     </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id case08_xml}">
     <title>case08.xml</title>
     <para>
     The resulting XML data looks like this:
     <programlisting role="tutorial">
     <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<music_company date_generated="2005-08-23T14:52:50">
    <store STOREID="1">
        <STORE_SALES>10</STORE_SALES>
        <STORE_EMPLOYEES>6</STORE_EMPLOYEES>
        <manager MANAGER_EMPLOYEEID="1">
            <MANAGER_EMPLOYEENAME>Michael Jones</MANAGER_EMPLOYEENAME>
        </manager>
        <address>
            <COUNTRY>US</COUNTRY>
            <STATE>NY</STATE>
            <CITY>New York</CITY>
            <STREET>Broadway &amp; 72nd Str</STREET>
            <PHONE>123 456 7890</PHONE>
        </address>
        <department departmentid="1">
            <departmentSales>10</departmentSales>
            <departmentEmployees>3</departmentEmployees>
            <departmentname>Sales</departmentname>
            <department_head departmentHeadEmployeeid="1">
                <departmentHeadEmployeename>Michael Jones</departmentHeadEmployeename>
            </department_head>
            <employees>
                <employee Employeeid="1">
                    <Employeename>Michael Jones</Employeename>
                    <sales>
                        <sale SALEID="1">
                            <TIMESTAMP>2005-05-25 16:32:00</TIMESTAMP>
                            <customer customerid="1">
                                <first_name>Jane</first_name>
                                <last_name>Doe</last_name>
                                <email>jane.doe@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="7">
                            <TIMESTAMP>2005-07-10 15:03:00</TIMESTAMP>
                            <customer customerid="7">
                                <first_name>Nick</first_name>
                                <last_name>Fallow</last_name>
                                <email>nick.fallow@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="16">
                            <TIMESTAMP>2005-06-05 12:56:12</TIMESTAMP>
                            <customer customerid="2">
                                <first_name>John</first_name>
                                <last_name>Doe</last_name>
                                <email>john.doe@example.com</email>
                            </customer>
                            <album albumid="3">
                                <title>Shaft</title>
                                <published_year>1972</published_year>
                                <comment>he's the man</comment>
                                <artist artistid="2">
                                    <name>Isaac Hayes</name>
                                    <birthyear>1942</birthyear>
                                    <birthplace>Tennessee</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="19">
                            <TIMESTAMP>2005-07-10 16:03:01</TIMESTAMP>
                            <customer customerid="8">
                                <first_name>Ed</first_name>
                                <last_name>Burton</last_name>
                                <email>ed.burton@example.com</email>
                            </customer>
                            <album albumid="3">
                                <title>Shaft</title>
                                <published_year>1972</published_year>
                                <comment>he's the man</comment>
                                <artist artistid="2">
                                    <name>Isaac Hayes</name>
                                    <birthyear>1942</birthyear>
                                    <birthplace>Tennessee</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                    </sales>
                </employee>
                <employee Employeeid="2">
                    <Employeename>Susi Weintraub</Employeename>
                    <sales>
                        <sale SALEID="3">
                            <TIMESTAMP>2005-07-10 11:03:00</TIMESTAMP>
                            <customer customerid="3">
                                <first_name>Susan</first_name>
                                <last_name>Green</last_name>
                                <email>susan.green@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="9">
                            <TIMESTAMP>2005-07-10 18:03:00</TIMESTAMP>
                            <customer customerid="9">
                                <first_name>Jack</first_name>
                                <last_name>Woo</last_name>
                                <email>jack.woo@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="17">
                            <TIMESTAMP>2005-07-10 10:03:32</TIMESTAMP>
                            <customer customerid="4">
                                <first_name>Victoria</first_name>
                                <last_name>Alt</last_name>
                                <email>victory.alt@example.com</email>
                            </customer>
                            <album albumid="3">
                                <title>Shaft</title>
                                <published_year>1972</published_year>
                                <comment>he's the man</comment>
                                <artist artistid="2">
                                    <name>Isaac Hayes</name>
                                    <birthyear>1942</birthyear>
                                    <birthplace>Tennessee</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="20">
                            <TIMESTAMP>2005-07-10 19:03:50</TIMESTAMP>
                            <customer customerid="10">
                                <first_name>Maria</first_name>
                                <last_name>Gonzales</last_name>
                                <email>maria.gonzales@example.com</email>
                            </customer>
                            <album albumid="3">
                                <title>Shaft</title>
                                <published_year>1972</published_year>
                                <comment>he's the man</comment>
                                <artist artistid="2">
                                    <name>Isaac Hayes</name>
                                    <birthyear>1942</birthyear>
                                    <birthplace>Tennessee</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                    </sales>
                </employee>
                <employee Employeeid="3">
                    <Employeename>Steve Hack</Employeename>
                    <sales>
                        <sale SALEID="5">
                            <TIMESTAMP>2005-07-10 13:03:00</TIMESTAMP>
                            <customer customerid="5">
                                <first_name>Will</first_name>
                                <last_name>Rippy</last_name>
                                <email>will.wippy@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="18">
                            <TIMESTAMP>2005-07-10 14:03:52</TIMESTAMP>
                            <customer customerid="6">
                                <first_name>Tim</first_name>
                                <last_name>Raw</last_name>
                                <email>tim.raw@example.com</email>
                            </customer>
                            <album albumid="3">
                                <title>Shaft</title>
                                <published_year>1972</published_year>
                                <comment>he's the man</comment>
                                <artist artistid="2">
                                    <name>Isaac Hayes</name>
                                    <birthyear>1942</birthyear>
                                    <birthplace>Tennessee</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                    </sales>
                </employee>
            </employees>
        </department>
        <department departmentid="2">
            <departmentSales>0</departmentSales>
            <departmentEmployees>3</departmentEmployees>
            <departmentname>Marketing</departmentname>
            <department_head departmentHeadEmployeeid="4">
                <departmentHeadEmployeename>Joan Kerr</departmentHeadEmployeename>
            </department_head>
            <employees>
                <employee Employeeid="4">
                    <Employeename>Joan Kerr</Employeename>
                    <sales />
                </employee>
                <employee Employeeid="5">
                    <Employeename>Marcus Roth</Employeename>
                    <sales />
                </employee>
                <employee Employeeid="6">
                    <Employeename>Jack Mack</Employeename>
                    <sales />
                </employee>
            </employees>
        </department>
    </store>
    <store STOREID="2">
        <STORE_SALES>10</STORE_SALES>
        <STORE_EMPLOYEES>6</STORE_EMPLOYEES>
        <manager MANAGER_EMPLOYEEID="2">
            <MANAGER_EMPLOYEENAME>Susi Weintraub</MANAGER_EMPLOYEENAME>
        </manager>
        <address>
            <COUNTRY>US</COUNTRY>
            <STATE>NY</STATE>
            <CITY>Larchmont</CITY>
            <STREET>Palmer Ave 71</STREET>
            <PHONE>456 7890</PHONE>
        </address>
        <department departmentid="3">
            <departmentSales>10</departmentSales>
            <departmentEmployees>3</departmentEmployees>
            <departmentname>Sales</departmentname>
            <department_head departmentHeadEmployeeid="7">
                <departmentHeadEmployeename>Rita Doktor</departmentHeadEmployeename>
            </department_head>
            <employees>
                <employee Employeeid="7">
                    <Employeename>Rita Doktor</Employeename>
                    <sales>
                        <sale SALEID="2">
                            <TIMESTAMP>2005-06-05 12:56:00</TIMESTAMP>
                            <customer customerid="2">
                                <first_name>John</first_name>
                                <last_name>Doe</last_name>
                                <email>john.doe@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="8">
                            <TIMESTAMP>2005-07-10 16:03:00</TIMESTAMP>
                            <customer customerid="8">
                                <first_name>Ed</first_name>
                                <last_name>Burton</last_name>
                                <email>ed.burton@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="11">
                            <TIMESTAMP>2005-05-25 16:23:00</TIMESTAMP>
                            <customer customerid="1">
                                <first_name>Jane</first_name>
                                <last_name>Doe</last_name>
                                <email>jane.doe@example.com</email>
                            </customer>
                            <album albumid="2">
                                <title>Curtis</title>
                                <published_year>1970</published_year>
                                <comment>that man ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="14">
                            <TIMESTAMP>2005-07-10 15:09:00</TIMESTAMP>
                            <customer customerid="7">
                                <first_name>Nick</first_name>
                                <last_name>Fallow</last_name>
                                <email>nick.fallow@example.com</email>
                            </customer>
                            <album albumid="2">
                                <title>Curtis</title>
                                <published_year>1970</published_year>
                                <comment>that man ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                    </sales>
                </employee>
                <employee Employeeid="8">
                    <Employeename>David Til</Employeename>
                    <sales>
                        <sale SALEID="4">
                            <TIMESTAMP>2005-07-10 10:03:00</TIMESTAMP>
                            <customer customerid="4">
                                <first_name>Victoria</first_name>
                                <last_name>Alt</last_name>
                                <email>victory.alt@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="10">
                            <TIMESTAMP>2005-07-10 19:03:00</TIMESTAMP>
                            <customer customerid="10">
                                <first_name>Maria</first_name>
                                <last_name>Gonzales</last_name>
                                <email>maria.gonzales@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="12">
                            <TIMESTAMP>2005-07-10 11:56:00</TIMESTAMP>
                            <customer customerid="3">
                                <first_name>Susan</first_name>
                                <last_name>Green</last_name>
                                <email>susan.green@example.com</email>
                            </customer>
                            <album albumid="2">
                                <title>Curtis</title>
                                <published_year>1970</published_year>
                                <comment>that man ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="15">
                            <TIMESTAMP>2005-07-10 18:49:00</TIMESTAMP>
                            <customer customerid="9">
                                <first_name>Jack</first_name>
                                <last_name>Woo</last_name>
                                <email>jack.woo@example.com</email>
                            </customer>
                            <album albumid="2">
                                <title>Curtis</title>
                                <published_year>1970</published_year>
                                <comment>that man ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                    </sales>
                </employee>
                <employee Employeeid="9">
                    <Employeename>Pia Eist</Employeename>
                    <sales>
                        <sale SALEID="6">
                            <TIMESTAMP>2005-07-10 14:03:00</TIMESTAMP>
                            <customer customerid="6">
                                <first_name>Tim</first_name>
                                <last_name>Raw</last_name>
                                <email>tim.raw@example.com</email>
                            </customer>
                            <album albumid="1">
                                <title>New World Order</title>
                                <published_year>1990</published_year>
                                <comment>the best ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                        <sale SALEID="13">
                            <TIMESTAMP>2005-07-10 13:12:00</TIMESTAMP>
                            <customer customerid="5">
                                <first_name>Will</first_name>
                                <last_name>Rippy</last_name>
                                <email>will.wippy@example.com</email>
                            </customer>
                            <album albumid="2">
                                <title>Curtis</title>
                                <published_year>1970</published_year>
                                <comment>that man ...</comment>
                                <artist artistid="1">
                                    <name>Curtis Mayfield</name>
                                    <birthyear>1920</birthyear>
                                    <birthplace>Chicago</birthplace>
                                    <genre>Soul</genre>
                                </artist>
                            </album>
                        </sale>
                    </sales>
                </employee>
            </employees>
        </department>
        <department departmentid="4">
            <departmentSales>0</departmentSales>
            <departmentEmployees>3</departmentEmployees>
            <departmentname>Marketing</departmentname>
            <department_head departmentHeadEmployeeid="10">
                <departmentHeadEmployeename>Hanna Poll</departmentHeadEmployeename>
            </department_head>
            <employees>
                <employee Employeeid="10">
                    <Employeename>Hanna Poll</Employeename>
                    <sales />
                </employee>
                <employee Employeeid="11">
                    <Employeename>Jim Wells</Employeename>
                    <sales />
                </employee>
                <employee Employeeid="12">
                    <Employeename>Sandra Wilson</Employeename>
                    <sales />
                </employee>
            </employees>
        </department>
    </store>
</music_company>
     ]]>
     </programlisting>
     </para>
    </refsect3>
    <refsect3 id="{@id case08_debug_php}">
     <title>case08_debug.php</title>
     <para>
     case08_debug.php:
     <programlisting role="php">
     <![CDATA[
<?php
class Mappers
{
    public static function departmentMapper($str)
    {
        //maps 'one_two_three' to 'oneTwoThree'
        return preg_replace("/(_)([a-z])/e", "strtoupper('\\2')", $str);
    }

    public static function employeeMapper($str)
    {
        //maps 'one_two_three' to 'OneTwoThree'
        return ucfirst(preg_replace("/(_)([a-z])/e", "strtoupper('\\2')", $str));
    }

    public function saleMapper($str)
    {
        //maps 'one_two_three' to 'ONETWOTHREE'
        return strtoupper(str_replace('_', '', $str));
    }
}

function mapArtist($str)
{
    //maps 'one_two_three' to 'onetwothree'
    return strtolower(str_replace('_', '', $str));
}

$myMappers = new Mappers();

require_once 'XML/Query2XML.php';
require_once 'XML/Query2XML/ISO9075Mapper.php';
require_once 'MDB2.php';
$query2xml = XML_Query2XML::factory(MDB2::factory('mysql://root@localhost/Query2XML_Tests'));

require_once 'Log.php';
$debugLogger = Log::factory('file', 'case08.log', 'XML_Query2XML');
$query2xml->enableDebugLog($debugLogger);

$query2xml->startProfiling();


$dom = $query2xml->getXML(
    "SELECT
         s.*,
         manager.employeeid AS manager_employeeid,
         manager.employeename AS manager_employeename,
         d.*,
         department_head.employeeid AS department_head_employeeid,
         department_head.employeename AS department_head_employeename,
         e.*,
         sa.*,
         c.*,
         al.*,
         ar.*,
         (SELECT COUNT(*) FROM sale WHERE sale.store_id = s.storeid) AS store_sales,
         (SELECT
            COUNT(*)
          FROM
            sale, employee, employee_department
          WHERE
            sale.employee_id = employee.employeeid
            AND
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_sales,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department, department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = department.departmentid
            AND
            department.store_id = s.storeid
         ) AS store_employees,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_employees
     FROM
         store s
          LEFT JOIN employee manager ON s.manager = manager.employeeid
         LEFT JOIN department d ON d.store_id = s.storeid
          LEFT JOIN employee department_head ON department_head.employeeid = d.department_head
          LEFT JOIN employee_department ed ON ed.department_id = d.departmentid
           LEFT JOIN employee e ON e.employeeid = ed.employee_id
            LEFT JOIN sale sa ON sa.employee_id = e.employeeid
             LEFT JOIN customer c ON c.customerid = sa.customer_id
             LEFT JOIN album al ON al.albumid = sa.album_id
              LEFT JOIN artist ar ON ar.artistid = al.artist_id",
    array(
        'rootTag' => 'music_company',
        'rowTag' => 'store',
        'idColumn' => 'storeid',
        'mapper' => 'strtoupper',
        'attributes' => array(
            'storeid'
        ),
        'elements' => array(
            'store_sales',
            'store_employees',
            'manager' => array(
                'idColumn' => 'manager_employeeid',
                'attributes' => array(
                    'manager_employeeid'
                ),
                'elements' => array(
                    'manager_employeename'
                )
            ),
            'address' => array(
                'elements' => array(
                    'country',
                    'state' => '#Helper::getStatePostalCode()',
                    'city',
                    'street',
                    'phone'
                )
            ),
            'department' => array(
                'idColumn' => 'departmentid',
                'mapper' => 'Mappers::departmentMapper',
                'attributes' => array(
                    'departmentid'
                ),
                'elements' => array(
                    'department_sales',
                    'department_employees',
                    'departmentname',
                    'department_head' => array(
                        'idColumn' => 'department_head_employeeid',
                        'attributes' => array(
                            'department_head_employeeid'
                        ),
                        'elements' => array(
                            'department_head_employeename'
                        )
                    ),
                    'employees' => array(
                        'rootTag' => 'employees',
                        'rowTag' => 'employee',
                        'idColumn' => 'employeeid',
                        'mapper' => array('Mappers', 'employeeMapper'),
                        'attributes' => array(
                            'employeeid'
                        ),
                        'elements' => array(
                            'employeename',
                            'sales' => array(
                                'rootTag' => 'sales',
                                'rowTag' => 'sale',
                                'idColumn' => 'saleid',
                                'mapper' => array($myMappers, 'saleMapper'),
                                'attributes' => array(
                                    'saleid'
                                ),
                                'elements' => array(
                                    'timestamp',
                                    'customer' => array(
                                        'idColumn' => 'customerid',
                                        'mapper' => false,
                                        'attributes' => array(
                                            'customerid'
                                        ),
                                        'elements' => array(
                                            'first_name',
                                            'last_name',
                                            'email'
                                        )
                                    ),
                                    'album' => array(
                                        'idColumn' => 'albumid',
                                        'mapper' => 'XML_Query2XML_ISO9075Mapper::map',
                                        'attributes' => array(
                                            'albumid'
                                        ),
                                        'elements' => array(
                                            'title',
                                            'published_year',
                                            'comment' => '?#Helper::summarizeComment(12)',
                                            'artist' => array(
                                                'idColumn' => 'artistid',
                                                'mapper' => 'mapArtist',
                                                'attributes' => array(
                                                    'artistid'
                                                ),
                                                'elements' => array(
                                                    'name',
                                                    'birth_year',
                                                    'birth_place',
                                                    'genre'
                                                )
                                            )
                                        ) // album elements
                                    ) //album array
                                ) //sales elements
                            ) //sales array
                        ) //employees elements
                    ) //employees array
                ) //department elements
            ) // department array
        ) //root elements
    ) //root
); //getXML method call

$root = $dom->firstChild;
$root->setAttribute('date_generated', date("Y-m-d\TH:i:s", 1124801570));

header('Content-Type: application/xml');

$dom->formatOutput = true;
print $dom->saveXML();

require_once 'File.php';
$fp = new File();
$fp->write('case08.profile', $query2xml->getProfile(), FILE_MODE_WRITE);


/**Static class that provides validation and parsing methods for
* generating XML.
*
* It is static so that we can easyly call its methods from inside
* Query2XML using eval'd code.
*/
class Helper
{
    /**Associative array of US postal state codes*/
    public static $statePostalCodes = array(
        'ALABAMA' => 'AL', 'ALASKA' => 'AK', 'AMERICAN SAMOA' => 'AS', 'ARIZONA' => 'AZ', 'ARKANSAS' => 'AR', 'CALIFORNIA' => 'CA',
        'COLORADO' => 'CO', 'CONNECTICUT' => 'CT', 'DELAWARE' => 'DE', 'DISTRICT OF COLUMBIA' => 'DC', 'FEDERATED STATES OF MICRONESIA' => 'FM',
        'FLORIDA' => 'FL', 'GEORGIA' => 'GA', 'GUAM' => 'GU', 'HAWAII' => 'HI', 'IDAHO' => 'ID', 'ILLINOIS' => 'IL', 'INDIANA' => 'IN',
        'IOWA' => 'IA', 'KANSAS' => 'KS', 'KENTUCKY' => 'KY', 'LOUISIANA' => 'LA', 'MAINE' => 'ME', 'MARSHALL ISLANDS' => 'MH', 'MARYLAND' => 'MD',
        'MASSACHUSETTS' => 'MA', 'MICHIGAN' => 'MI', 'MINNESOTA' => 'MN', 'MISSISSIPPI' => 'MS', 'MISSOURI' => 'MO', 'MONTANA' => 'MT',
        'NEBRASKA' => 'NE', 'NEVADA' => 'NV', 'NEW HAMPSHIRE' => 'NH', 'NEW JERSEY' => 'NJ', 'NEW JESEY' => 'NJ', 'NEW MEXICO' => 'NM', 'NEW YORK' => 'NY',
        'NORTH CAROLINA' => 'NC', 'NORTH DAKOTA' => 'ND', 'NORTHERN MARIANA ISLANDS' => 'MP', 'OHIO' => 'OH', 'OKLAHOMA' => 'OK', 'OREGON' => 'OR',
        'PALAU' => 'PW', 'PENNSYLVANIA' => 'PA', 'PUERTO RICO' => 'PR', 'RHODE ISLAND' => 'RI', 'SOUTH CAROLINA' => 'SC', 'SOUTH DAKOTA' => 'SD',
        'TENNESSEE' => 'TN', 'TEXAS' => 'TX', 'UTAH' => 'UT', 'VERMONT' => 'VT', 'VIRGIN ISLANDS' => 'VI', 'VIRGINIA' => 'VA', 'WASHINGTON' => 'WA',
        'WEST VIRGINIA' => 'WV', 'WISCONSIN' => 'WI', 'WYOMING' => 'WY'
    );

    /**Translates a US state name into its two-letter postal code.
    * If the translation fails, $state is returned unchanged
    * @param $record The record
    */
    public static function getStatePostalCode($record)
    {
        $state = $record["state"];
        $s = str_replace("  ", " ", trim(strtoupper($state)));
        if (isset(self::$statePostalCodes[$s])) {
            return self::$statePostalCodes[$s];
        } else {
            return $state;
        }
    }

    function summarize($str, $limit=50, $appendString=' ...')
    {
        if (strlen($str) > $limit) {
            $str = substr($str, 0, $limit - strlen($appendString)) . $appendString;
        }
        return $str;
    }

    function summarizeComment($record, $limit)
    {
        return self::summarize($record["comment"], $limit);
    }
}
?>
     ]]>
     </programlisting>
     The lines 36-38 do the debugging, line 40 and 222-224 the profiling. This will create
     case08.log and case08.profile.
     </para>
    </refsect3>
    <refsect3 id="{@id case08_log}">
     <title>case08.log</title>
     <para>
     The format of a debug log file is documented at {@tutorial XML_Query2XML.pkg#debugging}.
     Our debug log contains just a single query:
     <![CDATA[
Apr 20 13:33:47 XML_Query2XML [info] QUERY: SELECT
         s.*,
         manager.employeeid AS manager_employeeid,
         manager.employeename AS manager_employeename,
         d.*,
         department_head.employeeid AS department_head_employeeid,
         department_head.employeename AS department_head_employeename,
         e.*,
         sa.*,
         c.*,
         al.*,
         ar.*,
         (SELECT COUNT(*) FROM sale WHERE sale.store_id = s.storeid) AS store_sales,
         (SELECT
            COUNT(*)
          FROM
            sale, employee, employee_department
          WHERE
            sale.employee_id = employee.employeeid
            AND
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_sales,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department, department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = department.departmentid
            AND
            department.store_id = s.storeid
         ) AS store_employees,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_employees
     FROM
         store s
          LEFT JOIN employee manager ON s.manager = manager.employeeid
         LEFT JOIN department d ON d.store_id = s.storeid
          LEFT JOIN employee department_head ON department_head.employeeid = d.department_head
          LEFT JOIN employee_department ed ON ed.department_id = d.departmentid
           LEFT JOIN employee e ON e.employeeid = ed.employee_id
            LEFT JOIN sale sa ON sa.employee_id = e.employeeid
             LEFT JOIN customer c ON c.customerid = sa.customer_id
             LEFT JOIN album al ON al.albumid = sa.album_id
              LEFT JOIN artist ar ON ar.artistid = al.artist_id
Apr 20 13:33:47 XML_Query2XML [info] DONE
     ]]>
     </para>
    </refsect3>
    <refsect3 id="{@id case08_profile}">
     <title>case08.profile</title>
     <para>
     The format of the output is documented under
     {@tutorial XML_Query2XML.pkg#profiling.getprofile}:
     <![CDATA[
FROM_DB FROM_CACHE CACHED AVG_DURATION DURATION_SUM SQL
1       0          false  0.0101430416 0.0101430416 SELECT
         s.*,
         manager.employeeid AS manager_employeeid,
         manager.employeename AS manager_employeename,
         d.*,
         department_head.employeeid AS department_head_employeeid,
         department_head.employeename AS department_head_employeename,
         e.*,
         sa.*,
         c.*,
         al.*,
         ar.*,
         (SELECT COUNT(*) FROM sale WHERE sale.store_id = s.storeid) AS store_sales,
         (SELECT
            COUNT(*)
          FROM
            sale, employee, employee_department
          WHERE
            sale.employee_id = employee.employeeid
            AND
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_sales,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department, department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = department.departmentid
            AND
            department.store_id = s.storeid
         ) AS store_employees,
         (SELECT
            COUNT(*)
          FROM
            employee, employee_department
          WHERE
            employee_department.employee_id = employee.employeeid
            AND
            employee_department.department_id = d.departmentid
         ) AS department_employees
     FROM
         store s
          LEFT JOIN employee manager ON s.manager = manager.employeeid
         LEFT JOIN department d ON d.store_id = s.storeid
          LEFT JOIN employee department_head ON department_head.employeeid = d.department_head
          LEFT JOIN employee_department ed ON ed.department_id = d.departmentid
           LEFT JOIN employee e ON e.employeeid = ed.employee_id
            LEFT JOIN sale sa ON sa.employee_id = e.employeeid
             LEFT JOIN customer c ON c.customerid = sa.customer_id
             LEFT JOIN album al ON al.albumid = sa.album_id
              LEFT JOIN artist ar ON ar.artistid = al.artist_id

TOTAL_DURATION: 0.36341714859009
DB_DURATION:    0.20340394973755
     ]]>
     </para>
    </refsect3>
   </refsect2>
   <refsect2 id="{@id finalnotes}">
    <title>Final Notes on the case studies</title>
    <para>
     The files of all cases are installed in $PHP_PEAR_DOC_DIR/XML_Query2XML/cases/.
    </para>
   </refsect2>
  </refsect1>

  <refsect1 id="{@id sqlddl}">
   <title>SQL DDL used in all examples</title>
   <para>
   	In all the examples a MySQL database created with the SQL DDL shown below is used.
   	You might also want to have a look at the
   	{@link http://query2xml.sourceforge.net/docs/Query2XML_Tests.jpg ER diagram}.
   	Note: the unit tests by default use the SQLite 2 database found at
   	$PHP_PEAR_TEST_DIR/XML_Query2XML/tests/Query2XML_Tests. If you want to run
   	all unit tests you have to install
   	the MySQL DDL $PHP_PEAR_TEST_DIR/XML_Query2XML/tests/Query2XML_Tests.sql
   	or the PostgreSQL DDL $PHP_PEAR_TEST_DIR/XML_Query2XML/tests/Query2XML_Tests.psql.
   </para>
   <para>
    Please we use a certain naming convention for primary and foreign keys:
    <itemizedlist>
     <listitem>
      For primary keys we use "&lt;table_name&gt;id".
     </listitem>
     <listitem>
      For foreign keys we use "&lt;foreign_table_name&gt;_id".
     </listitem>
    </itemizedlist>
    <![CDATA[
CREATE DATABASE Query2XML_Tests;
USE Query2XML_Tests;


CREATE TABLE artist (
    artistid INT NOT NULL AUTO_INCREMENT,
    name VARCHAR(255),
    birth_year Int,
    birth_place VARCHAR(255),
    genre VARCHAR(255),
    UNIQUE (artistid),
    PRIMARY KEY (artistid)
);

CREATE TABLE customer (
    customerid INT NOT NULL AUTO_INCREMENT,
    first_name VARCHAR(255),
    last_name VARCHAR(255),
    email VARCHAR(255),
    UNIQUE (customerid),
    PRIMARY KEY (customerid)
);

CREATE TABLE album (
    albumid INT NOT NULL AUTO_INCREMENT,
    artist_id INT NOT NULL,
    title VARCHAR(255),
    published_year Int,
    comment VARCHAR(255),
    UNIQUE (albumid),
    PRIMARY KEY (albumid),
    FOREIGN KEY (artist_id) REFERENCES artist (artistid)
);

CREATE TABLE employee (
    employeeid INT NOT NULL AUTO_INCREMENT,
    employeename VARCHAR(255),
    UNIQUE (employeeid),
    PRIMARY KEY (employeeid)
);

CREATE TABLE store (
    storeid INT NOT NULL AUTO_INCREMENT,
    manager INT NOT NULL,
    country VARCHAR(255),
    state VARCHAR(255),
    city VARCHAR(255),
    street VARCHAR(255),
    phone VARCHAR(255),
    building_xmldata TEXT,
    UNIQUE (storeid),
    PRIMARY KEY (storeid),
    FOREIGN KEY (manager) REFERENCES employee (employeeid)
);

CREATE TABLE department (
    departmentid INT NOT NULL AUTO_INCREMENT,
    store_id INT NOT NULL,
    department_head INT NOT NULL,
    departmentname VARCHAR(255),
    UNIQUE (departmentid),
    PRIMARY KEY (departmentid),
    FOREIGN KEY (department_head) REFERENCES employee (employeeid),
    FOREIGN KEY (store_id) REFERENCES store (storeid)
);

CREATE TABLE employee_department (
    employee_id INT NOT NULL,
    department_id INT NOT NULL,
    PRIMARY KEY (employee_id,department_id),
    FOREIGN KEY (employee_id) REFERENCES employee (employeeid),
    FOREIGN KEY (department_id) REFERENCES department (departmentid)
);

CREATE TABLE sale (
    saleid INT NOT NULL AUTO_INCREMENT,
    album_id INT NOT NULL,
    customer_id INT NOT NULL,
    employee_id INT NOT NULL,
    store_id INT NOT NULL,
    timestamp Timestamp(14),
    UNIQUE (saleid),
    PRIMARY KEY (saleid),
    FOREIGN KEY (employee_id) REFERENCES employee (employeeid),
    FOREIGN KEY (album_id) REFERENCES album (albumid),
    FOREIGN KEY (customer_id) REFERENCES customer (customerid),
    FOREIGN KEY (store_id) REFERENCES store (storeid)
);



INSERT INTO artist (artistid, name, birth_year, birth_place, genre) VALUES(1, 'Curtis Mayfield', 1920, 'Chicago', 'Soul');
INSERT INTO artist (artistid, name, birth_year, birth_place, genre) VALUES(2, 'Isaac Hayes', 1942, 'Tennessee', 'Soul');
INSERT INTO artist (artistid, name, birth_year, birth_place, genre) VALUES(3, 'Ray Charles', 1930, 'Mississippi', 'Country and Soul');

INSERT INTO album (albumid, artist_id, title, published_year, comment) VALUES(1, 1, 'New World Order', 1990, 'the best ever!');
INSERT INTO album (albumid, artist_id, title, published_year, comment) VALUES(2, 1, 'Curtis', 1970, 'that man\'s got somthin\' to say');
INSERT INTO album (albumid, artist_id, title, published_year, comment) VALUES(3, 2, 'Shaft', 1972, 'he\'s the man');

INSERT INTO customer (customerid, first_name, last_name, email) VALUES(1, 'Jane', 'Doe', 'jane.doe@example.com');
INSERT INTO customer (customerid, first_name, last_name, email) VALUES(2, 'John', 'Doe', 'john.doe@example.com');
INSERT INTO customer (customerid, first_name, last_name, email) VALUES(3, 'Susan', 'Green', 'susan.green@example.com');
INSERT INTO customer (customerid, first_name, last_name, email) VALUES(4, 'Victoria', 'Alt', 'victory.alt@example.com');
INSERT INTO customer (customerid, first_name, last_name, email) VALUES(5, 'Will', 'Rippy', 'will.wippy@example.com');
INSERT INTO customer (customerid, first_name, last_name, email) VALUES(6, 'Tim', 'Raw', 'tim.raw@example.com');
INSERT INTO customer (customerid, first_name, last_name, email) VALUES(7, 'Nick', 'Fallow', 'nick.fallow@example.com');
INSERT INTO customer (customerid, first_name, last_name, email) VALUES(8, 'Ed', 'Burton', 'ed.burton@example.com');
INSERT INTO customer (customerid, first_name, last_name, email) VALUES(9, 'Jack', 'Woo', 'jack.woo@example.com');
INSERT INTO customer (customerid, first_name, last_name, email) VALUES(10, 'Maria', 'Gonzales', 'maria.gonzales@example.com');

INSERT INTO employee (employeeid, employeename) VALUES(1, 'Michael Jones');
INSERT INTO employee (employeeid, employeename) VALUES(2, 'Susi Weintraub');
INSERT INTO employee (employeeid, employeename) VALUES(3, 'Steve Hack');
INSERT INTO employee (employeeid, employeename) VALUES(4, 'Joan Kerr');
INSERT INTO employee (employeeid, employeename) VALUES(5, 'Marcus Roth');
INSERT INTO employee (employeeid, employeename) VALUES(6, 'Jack Mack');
INSERT INTO employee (employeeid, employeename) VALUES(7, 'Rita Doktor');
INSERT INTO employee (employeeid, employeename) VALUES(8, 'David Til');
INSERT INTO employee (employeeid, employeename) VALUES(9, 'Pia Eist');
INSERT INTO employee (employeeid, employeename) VALUES(10, 'Hanna Poll');
INSERT INTO employee (employeeid, employeename) VALUES(11, 'Jim Wells');
INSERT INTO employee (employeeid, employeename) VALUES(12, 'Sandra Wilson');

INSERT INTO store (storeid, manager, country, state, city, street, phone, building_xmldata) VALUES(1, 1, 'US', 'New York', 'New York', 'Broadway & 72nd Str', '123 456 7890', '<building><floors>4</floors><elevators>2</elevators><square_meters>3200</square_meters></building>');
INSERT INTO store (storeid, manager, country, state, city, street, phone, building_xmldata) VALUES(2, 2, 'US', 'New York', 'Larchmont', 'Palmer Ave 71', '456 7890', '<building><floors>2</floors><elevators>1</elevators><square_meters>400</square_meters></building>');

INSERT INTO department (departmentid, store_id, department_head, departmentname) VALUES(1, 1, 1, 'Sales');
INSERT INTO department (departmentid, store_id, department_head, departmentname) VALUES(2, 1, 4, 'Marketing');
INSERT INTO department (departmentid, store_id, department_head, departmentname) VALUES(3, 2, 7, 'Sales');
INSERT INTO department (departmentid, store_id, department_head, departmentname) VALUES(4, 2, 10, 'Marketing');

INSERT INTO employee_department (employee_id, department_id) VALUES(1, 1);
INSERT INTO employee_department (employee_id, department_id) VALUES(2, 1);
INSERT INTO employee_department (employee_id, department_id) VALUES(3, 1);
INSERT INTO employee_department (employee_id, department_id) VALUES(4, 2);
INSERT INTO employee_department (employee_id, department_id) VALUES(5, 2);
INSERT INTO employee_department (employee_id, department_id) VALUES(6, 2);
INSERT INTO employee_department (employee_id, department_id) VALUES(7, 3);
INSERT INTO employee_department (employee_id, department_id) VALUES(8, 3);
INSERT INTO employee_department (employee_id, department_id) VALUES(9, 3);
INSERT INTO employee_department (employee_id, department_id) VALUES(10, 4);
INSERT INTO employee_department (employee_id, department_id) VALUES(11, 4);
INSERT INTO employee_department (employee_id, department_id) VALUES(12, 4);

INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (1,  1,  1, 1, 1, '2005-05-25 16:32:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (2,  2,  1, 7, 2, '2005-06-05 12:56:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (3,  3,  1, 2, 1, '2005-07-10 11:03:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (4,  4,  1, 8, 2, '2005-07-10 10:03:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (5,  5,  1, 3, 1, '2005-07-10 13:03:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (6,  6,  1, 9, 2, '2005-07-10 14:03:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (7,  7,  1, 1, 1, '2005-07-10 15:03:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (8,  8,  1, 7, 2, '2005-07-10 16:03:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (9,  9,  1, 2, 1, '2005-07-10 18:03:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (10, 10, 1, 8, 2, '2005-07-10 19:03:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (11, 1,  2, 7, 2, '2005-05-25 16:23:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (12, 3,  2, 8, 2, '2005-07-10 11:56:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (13, 5,  2, 9, 2, '2005-07-10 13:12:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (14, 7,  2, 7, 2, '2005-07-10 15:09:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (15, 9,  2, 8, 2, '2005-07-10 18:49:00');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (16, 2,  3, 1, 1, '2005-06-05 12:56:12');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (17, 4,  3, 2, 1, '2005-07-10 10:03:32');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (18, 6,  3, 3, 1, '2005-07-10 14:03:52');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (19, 8,  3, 1, 1, '2005-07-10 16:03:01');
INSERT INTO sale (saleid, customer_id, album_id, employee_id, store_id, timestamp) VALUES (20, 10, 3, 2, 1, '2005-07-10 19:03:50');
   ]]>
  </para>
 </refsect1>

 <refsect1 id="{@id copyright_notice}">
  <title>Copyright Notice</title>
  <para>
   Copyright: Lukas Feiler 2006
  </para>
  <para>
  	<emphasis>LICENSE:</emphasis>This source file is subject to version 2.1 of the LGPL that is bundled with this package in the file LICENSE.
  </para>
 </refsect1>
</refentry>