<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 294410 $ -->

<chapter xml:id="simplexml.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.examples;
 <section xml:id="simplexml.examples-basic">
  <title>Basic usage</title>
  <para>
   Many examples in this reference require an XML string. Instead of
   repeating this string in every example, we put it into a file which
   we include in each example. This included file is shown in the 
   following example section. Alternatively, you could create an XML
   document and read it with <function>simplexml_load_file</function>.
  </para>
  <para>
   <example>
    <title>Include file example.php with XML string</title>
    <programlisting role="php" xml:id="simplexml.examples.movie">
<![CDATA[
<?php
$xmlstr = <<<XML
<?xml version='1.0' standalone='yes'?>
<movies>
 <movie>
  <title>PHP: Behind the Parser</title>
  <characters>
   <character>
    <name>Ms. Coder</name>
    <actor>Onlivia Actora</actor>
   </character>
   <character>
    <name>Mr. Coder</name>
    <actor>El Act&#211;r</actor>
   </character>
  </characters>
  <plot>
   So, this language. It's like, a programming language. Or is it a
   scripting language? All is revealed in this thrilling horror spoof
   of a documentary.
  </plot>
  <great-lines>
   <line>PHP solves all my web problems</line>
  </great-lines>
  <rating type="thumbs">7</rating>
  <rating type="stars">5</rating>
 </movie>
</movies>
XML;
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   The simplicity of SimpleXML appears most clearly when one extracts
   a string or number from a basic XML document.
   <example>
    <title>Getting <literal>&lt;plot&gt;</literal></title>
    <programlisting role="php"><![CDATA[
<?php
include 'example.php';

$xml = new SimpleXMLElement($xmlstr);

echo $xml->movie[0]->plot; // "So this language. It's like..."
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Accessing elements within an XML document that contain characters not permitted under 
   PHP's naming convention (e.g. the hyphen) can be accomplished by encapsulating the
   element name within braces and the apostrophe.
   <example>
    <title>Getting <literal>&lt;line&gt;</literal></title>
    <programlisting role="php">
<![CDATA[
<?php
include 'example.php';

$xml = new SimpleXMLElement($xmlstr);

echo $xml->movie->{'great-lines'}->line; // "PHP solves all my web problems"
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Accessing non-unique elements in SimpleXML</title>
    <simpara>
     When multiple instances of an element exist as children of
     a single parent element, normal iteration techniques apply.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
include 'example.php';

$xml = new SimpleXMLElement($xmlstr);

/* For each <movie> node, we echo a separate <plot>. */
foreach ($xml->movie as $movie) {
   echo $movie->plot, '<br />';
}

?>
]]>
    </programlisting>
   </example>
  </para>
  <note>
   <para>
    Properties (<literal>$xml->movie</literal> in previous example) are not
    arrays. They are <link linkend="class.iterator">iterable</link> and
    <link linkend="class.arrayaccess">accessible</link> objects.
   </para>
  </note>
  <para>
   <example>
    <title>Using attributes</title>
    <simpara>
     So far, we have only covered the work of reading element names
     and their values. SimpleXML can also access element attributes.
     Access attributes of an element just as you would elements
     of an <type>array</type>.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
include 'example.php';

$xml = new SimpleXMLElement($xmlstr);

/* Access the <rating> nodes of the first movie.
 * Output the rating scale, too. */
foreach ($xml->movie[0]->rating as $rating) {
    switch((string) $rating['type']) { // Get attributes as element indices
    case 'thumbs':
        echo $rating, ' thumbs up';
        break;
    case 'stars':
        echo $rating, ' stars';
        break;
    }
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Comparing Elements and Attributes with Text</title>
    <simpara>
     To compare an element or attribute with a string or pass it into a 
     function that requires a string, you must cast it to a string using 
     <literal>(string)</literal>. Otherwise, PHP treats the element as an object.
    </simpara>
    <programlisting role="php"><![CDATA[
<?php     
include 'example.php';

$xml = new SimpleXMLElement($xmlstr);

if ((string) $xml->movie->title == 'PHP: Behind the Parser') {
    print 'My favorite movie.';
}

htmlentities((string) $xml->movie->title);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Comparing Two Elements</title>
    <simpara>
     Two SimpleXMLElements are considered different even if they point to the
     same element since PHP 5.2.0.
    </simpara>
    <programlisting role="php"><![CDATA[
<?php
$el1 = new SimpleXMLElement($xmlstr);
$el2 = new SimpleXMLElement($xmlstr);
var_dump($el1 == $el2); // false since PHP 5.2.0
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Using XPath</title>
    <simpara>
     SimpleXML includes built-in <acronym>XPath</acronym> support.
     To find all <literal>&lt;character&gt;</literal> elements:
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
include 'example.php';
$xml = new SimpleXMLElement($xmlstr);

foreach ($xml->xpath('//character') as $character) {
    echo $character->name, 'played by ', $character->actor, '<br />';
}
?>
]]>
    </programlisting>
    <simpara>
     '<literal>//</literal>' serves as a wildcard. To specify absolute
     paths, omit one of the slashes.
    </simpara>
   </example>
  </para>
  <para>
   <example>
    <title>Setting values</title>
    <simpara>
     Data in SimpleXML doesn't have to be constant. The object allows
     for manipulation of all of its elements.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
include 'example.php';
$xml = new SimpleXMLElement($xmlstr);

$xml->movie[0]->characters->character[0]->name = 'Miss Coder';

echo $xml->asXML();
?>
]]>
    </programlisting>
    <simpara>
     The above code will output a new XML document, just like the original,
     except that the new XML will change Ms. Coder to Miss Coder.
    </simpara>
   </example>
  </para>
  <para>
   <example>
    <title>Adding elements and attributes</title>
    <simpara>
     Since PHP 5.1.3, SimpleXML has had the ability to easily add children and
     attributes.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
include 'example.php';
$xml = new SimpleXMLElement($xmlstr);

$character = $xml->movie[0]->characters->addChild('character');
$character->addChild('name', 'Mr. Parser');
$character->addChild('actor', 'John Doe');

$rating = $xml->movie[0]->addChild('rating', 'PG');
$rating->addAttribute('type', 'mpaa');

echo $xml->asXML();
?>
]]>
    </programlisting>
    <simpara>
     The above code will output an XML document based on the original but 
     having a new character and rating.
    </simpara>
   </example>
  </para>
  <para>
   <example>
    <title>DOM Interoperability</title>
    <simpara>
     PHP has a mechanism to convert XML nodes between SimpleXML
     and DOM formats. This example shows how one might change
     a DOM element to SimpleXML.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
$dom = new domDocument;
$dom->loadXML('<books><book><title>blah</title></book></books>');
if (!$dom) {
     echo 'Error while parsing the document';
     exit;
}

$s = simplexml_import_dom($dom);

echo $s->book[0]->title;
?>
]]>
    </programlisting>
   </example>
  </para>
 </section>

 <section xml:id="simplexml.examples-errors">
  <title>Dealing with XML errors</title>
  <para>
   Dealing with XML errors when loading documents is a very simple task.
   Using the <link linkend="book.libxml">libxml</link> functionality it is
   possible to suppress all XML errors when loading the document and then
   iterate over the errors.
  </para>
  <para>
   The <classname>libXMLError</classname> object, returned by
   <function>libxml_get_errors</function>, contains several properties
   including the <link linkend="libxmlerror.props.message">message</link>,
   <link linkend="libxmlerror.props.line">line</link> and
   <link linkend="libxmlerror.props.column">column</link> (position) of the
   error.
  </para>
  <para>
   <example>
    <title>Loading broken XML string</title>
    <programlisting role="php" xml:id="simplexml.examples.error">
<![CDATA[
<?php
libxml_use_internal_errors(true);
$sxe = simplexml_load_string("<?xml version='1.0'><broken><xml></broken>");
if (!$sxe) {
    echo "Failed loading XML\n";
    foreach(libxml_get_errors() as $error) {
        echo "\t", $error->message;
    }
}
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Failed loading XML
    Blank needed here
    parsing XML declaration: '?>' expected
    Opening and ending tag mismatch: xml line 1 and broken
    Premature end of data in tag broken line 1
]]>
    </screen>
   </example>
  </para>
  <section role="seealso"><!-- {{{ -->
   &reftitle.seealso;
   <para>
    <simplelist>
     <member><function>libxml_use_internal_errors</function></member>
     <member><function>libxml_get_errors</function></member>
     <member><xref linkend="class.libxmlerror" /></member>
    </simplelist>
   </para>
  </section>
 </section>

</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->