<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
 <reference id="ref.simplexml">
  <title>SimpleXML functions</title>
  <titleabbrev>SimpleXML</titleabbrev>

  <partintro>
   <section id="simplexml.intro">
    &reftitle.intro;
    &warn.experimental;
    <para>
     The SimpleXML extension provides a very simple and easily usable
     toolset to convert XML to an object that can be processed with
     normal property selectors and array iterators.
    </para>
   </section>

   <section id="simplexml.installation">
    &reftitle.install;
    <para>
     This extension is only available if PHP was configured with
     <option role="configure">--enable-simplexml</option>. The
     PHP configuration script does this by default.
    </para>
   </section>
   
   <section id="simplexml.examples">
    &reftitle.examples;
    <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" 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>
  <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 = simplexml_load_string($xmlstr);

echo $xml->movie[0]->plot; // "So this language. It's like..."
?>
]]>
      </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 = simplexml_load_string($xmlstr);

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

?>
]]>
      </programlisting>
     </example>
    </para>
    <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 = simplexml_load_string($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 with a string or pass it into a 
       function, 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 = simplexml_load_string($xmlstr);

if ((string) $xml->movie->title == 'PHP: Behind the Parser') {
    print 'My favorite movie.';
}
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title>Using Xpath</title>
      <simpara>
       SimpleXML includes builtin <acronym>Xpath</acronym> support.
       To find all <literal>&lt;character&gt;</literal> elements:
      </simpara>
      <programlisting role="php">
<![CDATA[
<?php
include 'example.php';
$xml = simplexml_load_string($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 = simplexml_load_string($xmlstr);

$xml->movie[0]->actor[0]->age = '21';

echo $xml->asXML();
?>
]]>
      </programlisting>
      <simpara>
       The above code will output a new XML document, just like the original,
       except that the new XML will define Ms. Coder's age as 21.
      </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>
  </partintro>

&reference.simplexml.functions;

 </reference>
<!-- 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:"../../../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
-->