MFB: Upgrade to the new-reference-structure

- (Created missing setup sections in setup.xml, if any)
 - Moved the intro to book.xml
 - Changed the intro ID from <extname>.intro to intro.<extname>
 - Created empty constants.xml appendix
 - Moved the examples into its own chapter
	NOTE: The chapter ID is simplexml.examples, the old simplexml.examples is now simplexml.examples-basic
 - Moved the requirement section and the configure entity to setup.xml


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@248929 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hannes Magnusson 2007-12-24 13:17:58 +00:00
parent d06bb5702b
commit 2339ba0241
5 changed files with 436 additions and 300 deletions

View file

@ -0,0 +1,47 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<!-- Purpose: xml -->
<!-- Membership: bundled, external -->
<book xml:id="book.simplexml" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>SimpleXML</title>
<!-- {{{ preface -->
<preface xml:id="intro.simplexml">
&reftitle.intro;
<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>
</preface>
<!-- }}} -->
&reference.simplexml.setup;
&reference.simplexml.constants;
&reference.simplexml.examples;
&reference.simplexml.reference;
</book>
<!-- 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
-->

View file

@ -0,0 +1,29 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.5 $ -->
<appendix xml:id="simplexml.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.constants;
&no.constants;
</appendix>
<!-- 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
-->

View file

@ -0,0 +1,299 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<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">
<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>
<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>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>
</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:"../../../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
-->

View file

@ -1,308 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.24 $ -->
<!-- Purpose: xml -->
<!-- Membership: bundled, external -->
<!-- $Revision: 1.25 $ -->
<reference xml:id="ref.simplexml" xmlns="http://docbook.org/ns/docbook">
<title>SimpleXML functions</title>
<titleabbrev>SimpleXML</titleabbrev>
<reference xml:id="ref.simplexml" xmlns="http://docbook.org/ns/docbook">
<title>SimpleXML functions</title>
<partintro>
<section xml:id="simplexml.intro">
&reftitle.intro;
<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 xml:id="simplexml.requirements">
&reftitle.required;
<para>
The SimpleXML extension requires PHP 5.
</para>
</section>
&reference.simplexml.entities.functions;
&reference.simplexml.configure;
<section xml: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" 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';
</reference>
$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>
<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>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>
</partintro>
&reference.simplexml.entities.functions;
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

View file

@ -0,0 +1,56 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="simplexml.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<!-- {{{ Requirements -->
<section xml:id="simplexml.requirements">
&reftitle.required;
<para>
The SimpleXML extension requires PHP 5.
</para>
</section>
<!-- }}} -->
<!-- {{{ Installation -->
&reference.simplexml.configure;
<!-- }}} -->
<!-- {{{ Configuration -->
<section xml:id="simplexml.configuration">
&reftitle.runtime;
&no.config;
</section>
<!-- }}} -->
<!-- {{{ Resources -->
<section xml:id="simplexml.resources">
&reftitle.resources;
&no.resource;
</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:"../../../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
-->