cvs: phpdoc /en/reference/xml book.xml case-folding.xml constants.xml encoding.xml error-codes.xml eventhandlers.xml examples.xml reference.xml
setup.xml
| From: | Hannes Magnusson | Date: | Sun, 23 Dec 2007 22:39:46 +0000 |
| Subject: | cvs: phpdoc /en/reference/xml book.xml case-folding.xml constants.xml encoding.xml error-codes.xml eventhandlers.xml examples.xml reference.xml setup.xml |
||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-793@lists.php.net to get a copy of this message | ||
bjori Sun Dec 23 22:39:46 2007 UTC
Modified files:
/phpdoc/en/reference/xml book.xml case-folding.xml encoding.xml
error-codes.xml eventhandlers.xml
examples.xml setup.xml constants.xml
reference.xml
Log:
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>
- Moved the constants entity to book.xml
- Changed constants.xml to be an appendix
- Changed the xml.encoding section to be an article (encoding.xml)
- Changed the xml.case-folding section to be an article (case-folding)
- Changed the xml.error-codes section to be an article (error-codes.xml)
- Changed the xml.eventhandlers section to be an article (eventhandlers.xml)
- Moved the examples into its own chapter (examples.xml)
- Moved the configuration, requirements and resources sections to setup.xml
- Moved the configure entity to setup.xml
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/book.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/book.xml diff -u /dev/null phpdoc/en/reference/xml/book.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/book.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<!-- Purpose: xml --> +<!-- Membership: bundled, external --> + +<book xml:id="book.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>XML Parser</title> + + <!-- {{{ preface --> + <preface xml:id="intro.xml"> + &reftitle.intro; + <para> + XML (eXtensible Markup Language) is a data format for structured + document interchange on the Web. It is a standard defined by + The World Wide Web consortium (W3C). Information about XML and + related technologies can be found at <link + xlink:href="&url.xml;">&url.xml;</link>. + </para> + <para> + This PHP extension implements support for James Clark's + <productname>expat</productname> in PHP. This toolkit lets you + parse, but not validate, XML documents. It supports three + source <link linkend="xml.encoding">character encodings</link> + also provided by PHP: <literal>US-ASCII</literal>, + <literal>ISO-8859-1</literal> and <literal>UTF-8</literal>. + <literal>UTF-16</literal> is not supported. + </para> + <para> + This extension lets you <link + linkend="function.xml-parser-create">create XML parsers</link> + and then define <emphasis>handlers</emphasis> for different XML + events. Each XML parser also has a few <link + linkend="function.xml-parser-set-option">parameters</link> you + can adjust. + </para> + </preface> + <!-- }}} --> + + &reference.xml.setup; + &reference.xml.constants; + &reference.xml.eventhandlers; + &reference.xml.case-folding; + &reference.xml.error-codes; + &reference.xml.encoding; + &reference.xml.examples; + &reference.xml.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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/case-folding.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/case-folding.xml diff -u /dev/null phpdoc/en/reference/xml/case-folding.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/case-folding.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<article xml:id="xml.case-folding" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Case Folding</title> + <para> + The element handler functions may get their element names + <glossterm>case-folded</glossterm>. Case-folding is defined by + the XML standard as "a process applied to a sequence of + characters, in which those identified as non-uppercase are + replaced by their uppercase equivalents". In other words, when + it comes to XML, case-folding simply means uppercasing. + </para> + <para> + By default, all the element names that are passed to the handler + functions are case-folded. This behaviour can be queried and + controlled per XML parser with the + <function>xml_parser_get_option</function> and + <function>xml_parser_set_option</function> functions, + respectively. + </para> +</article> + +<!-- 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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/encoding.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/encoding.xml diff -u /dev/null phpdoc/en/reference/xml/encoding.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/encoding.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<article xml:id="xml.encoding" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Character Encoding</title> + <para> + PHP's XML extension supports the <link + xlink:href="&url.unicode;">Unicode</link> character set through + different <glossterm>character encoding</glossterm>s. There are + two types of character encodings, <glossterm>source + encoding</glossterm> and <glossterm>target encoding</glossterm>. + PHP's internal representation of the document is always encoded + with <literal>UTF-8</literal>. + </para> + <para> + Source encoding is done when an XML document is <link + linkend="function.xml-parse">parsed</link>. Upon <link + linkend="function.xml-parser-create">creating an XML + parser</link>, a source encoding can be specified (this encoding + can not be changed later in the XML parser's lifetime). The + supported source encodings are <literal>ISO-8859-1</literal>, + <literal>US-ASCII</literal> and <literal>UTF-8</literal>. The + former two are single-byte encodings, which means that each + character is represented by a single byte. + <literal>UTF-8</literal> can encode characters composed by a + variable number of bits (up to 21) in one to four bytes. The + default source encoding used by PHP is + <literal>ISO-8859-1</literal>. + </para> + <para> + Target encoding is done when PHP passes data to XML handler + functions. When an XML parser is created, the target encoding + is set to the same as the source encoding, but this may be + changed at any point. The target encoding will affect character + data as well as tag names and processing instruction targets. + </para> + <para> + If the XML parser encounters characters outside the range that + its source encoding is capable of representing, it will return + an error. + </para> + <para> + If PHP encounters characters in the parsed XML document that can + not be represented in the chosen target encoding, the problem + characters will be "demoted". Currently, this means that such + characters are replaced by a question mark. + </para> +</article> + +<!-- 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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/error-codes.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/error-codes.xml diff -u /dev/null phpdoc/en/reference/xml/error-codes.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/error-codes.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<article xml:id="xml.error-codes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Error Codes</title> + <para> + The following constants are defined for XML error codes (as + returned by <function>xml_parse</function>): + <simplelist> + <member>XML_ERROR_NONE</member> + <member>XML_ERROR_NO_MEMORY</member> + <member>XML_ERROR_SYNTAX</member> + <member>XML_ERROR_NO_ELEMENTS</member> + <member>XML_ERROR_INVALID_TOKEN</member> + <member>XML_ERROR_UNCLOSED_TOKEN</member> + <member>XML_ERROR_PARTIAL_CHAR</member> + <member>XML_ERROR_TAG_MISMATCH</member> + <member>XML_ERROR_DUPLICATE_ATTRIBUTE</member> + <member>XML_ERROR_JUNK_AFTER_DOC_ELEMENT</member> + <member>XML_ERROR_PARAM_ENTITY_REF</member> + <member>XML_ERROR_UNDEFINED_ENTITY</member> + <member>XML_ERROR_RECURSIVE_ENTITY_REF</member> + <member>XML_ERROR_ASYNC_ENTITY</member> + <member>XML_ERROR_BAD_CHAR_REF</member> + <member>XML_ERROR_BINARY_ENTITY_REF</member> + <member>XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF</member> + <member>XML_ERROR_MISPLACED_XML_PI</member> + <member>XML_ERROR_UNKNOWN_ENCODING</member> + <member>XML_ERROR_INCORRECT_ENCODING</member> + <member>XML_ERROR_UNCLOSED_CDATA_SECTION</member> + <member>XML_ERROR_EXTERNAL_ENTITY_HANDLING</member> + </simplelist> + </para> +</article> + +<!-- 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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/eventhandlers.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/eventhandlers.xml diff -u /dev/null phpdoc/en/reference/xml/eventhandlers.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/eventhandlers.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<article xml:id="xml.eventhandlers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Event Handlers</title> + <para> + The XML event handlers defined are: + <table> + <title>Supported XML handlers</title> + <tgroup cols="2"> + <thead> + <row> + <entry>PHP function to set handler</entry> + <entry>Event description</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>xml_set_element_handler</function></entry> + <entry> + Element events are issued whenever the XML parser + encounters start or end tags. There are separate handlers + for start tags and end tags. + </entry> + </row> + <row> + <entry> + <function>xml_set_character_data_handler</function> + </entry> + <entry> + Character data is roughly all the non-markup contents of + XML documents, including whitespace between tags. Note + that the XML parser does not add or remove any whitespace, + it is up to the application (you) to decide whether + whitespace is significant. + </entry> + </row> + <row> + <entry> + <function>xml_set_processing_instruction_handler</function> + </entry> + <entry> + PHP programmers should be familiar with processing + instructions (PIs) already. <?php ?> is a processing + instruction, where <replaceable>php</replaceable> is called + the "PI target". The handling of these are + application-specific, except that all PI targets starting + with "XML" are reserved. + </entry> + </row> + <row> + <entry><function>xml_set_default_handler</function></entry> + <entry> + What goes not to another handler goes to the default + handler. You will get things like the XML and document + type declarations in the default handler. + </entry> + </row> + <row> + <entry> + <function>xml_set_unparsed_entity_decl_handler</function> + </entry> + <entry> + This handler will be called for declaration of an unparsed + (NDATA) entity. + </entry> + </row> + <row> + <entry> + <function>xml_set_notation_decl_handler</function> + </entry> + <entry> + This handler is called for declaration of a notation. + </entry> + </row> + <row> + <entry> + <function>xml_set_external_entity_ref_handler</function> + </entry> + <entry> + This handler is called when the XML parser finds a + reference to an external parsed general entity. This can + be a reference to a file or URL, for example. See <link + linkend="example.xml-external-entity">the external entity + example</link> for a demonstration. + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> +</article> + +<!-- 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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/examples.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/examples.xml diff -u /dev/null phpdoc/en/reference/xml/examples.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/examples.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,347 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<chapter xml:id="xml.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.examples; + <section xml:id="example.xml-structure"> + <title>XML Element Structure Example</title> + <para> + This first example displays the structure of the start elements in + a document with indentation. + <example> + <title>Show XML Element Structure</title> + <programlisting role="php"> +<![CDATA[ +<?php +$file = "data.xml"; +$depth = array(); + +function startElement($parser, $name, $attrs) +{ + global $depth; + for ($i = 0; $i < $depth[$parser]; $i++) { + echo " "; + } + echo "$name\n"; + $depth[$parser]++; +} + +function endElement($parser, $name) +{ + global $depth; + $depth[$parser]--; +} + +$xml_parser = xml_parser_create(); +xml_set_element_handler($xml_parser, "startElement", "endElement"); +if (!($fp = fopen($file, "r"))) { + die("could not open XML input"); +} + +while ($data = fread($fp, 4096)) { + if (!xml_parse($xml_parser, $data, feof($fp))) { + die(sprintf("XML error: %s at line %d", + xml_error_string(xml_get_error_code($xml_parser)), + xml_get_current_line_number($xml_parser))); + } +} +xml_parser_free($xml_parser); +?> +]]> + </programlisting> + </example> + </para> + </section> + + <section xml:id="example.xml-map-tags"> + <title>XML Tag Mapping Example</title> + <para> + <example> + <title>Map XML to HTML</title> + <para> + This example maps tags in an XML document directly to HTML + tags. Elements not found in the "map array" are ignored. Of + course, this example will only work with a specific XML + document type. + </para> + <programlisting role="php"> +<![CDATA[ +<?php +$file = "data.xml"; +$map_array = array( + "BOLD" => "B", + "EMPHASIS" => "I", + "LITERAL" => "TT" +); + +function startElement($parser, $name, $attrs) +{ + global $map_array; + if (isset($map_array[$name])) { + echo "<$map_array[$name]>"; + } +} + +function endElement($parser, $name) +{ + global $map_array; + if (isset($map_array[$name])) { + echo "</$map_array[$name]>"; + } +} + +function characterData($parser, $data) +{ + echo $data; +} + +$xml_parser = xml_parser_create(); +// use case-folding so we are sure to find the tag in $map_array +xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, true); +xml_set_element_handler($xml_parser, "startElement", "endElement"); +xml_set_character_data_handler($xml_parser, "characterData"); +if (!($fp = fopen($file, "r"))) { + die("could not open XML input"); +} + +while ($data = fread($fp, 4096)) { + if (!xml_parse($xml_parser, $data, feof($fp))) { + die(sprintf("XML error: %s at line %d", + xml_error_string(xml_get_error_code($xml_parser)), + xml_get_current_line_number($xml_parser))); + } +} +xml_parser_free($xml_parser); +?> +]]> + </programlisting> + </example> + </para> + </section> + + <section xml:id="example.xml-external-entity"> + <title>XML External Entity Example</title> + <para> + This example highlights XML code. It illustrates how to use an + external entity reference handler to include and parse other + documents, as well as how PIs can be processed, and a way of + determining "trust" for PIs containing code. + </para> + <para> + XML documents that can be used for this example are found below + the example (<filename>xmltest.xml</filename> and + <filename>xmltest2.xml</filename>.) + </para> + <para> + <example> + <title>External Entity Example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$file = "xmltest.xml"; + +function trustedFile($file) +{ + // only trust local files owned by ourselves + if (!eregi("^([a-z]+)://", $file) + && fileowner($file) == getmyuid()) { + return true; + } + return false; +} + +function startElement($parser, $name, $attribs) +{ + echo "<<font color=\"#0000cc\">$name</font>"; + if (count($attribs)) { + foreach ($attribs as $k => $v) { + echo " <font color=\"#009900\">$k</font>=\"<font + color=\"#990000\">$v</font>\""; + } + } + echo ">"; +} + +function endElement($parser, $name) +{ + echo "</<font color=\"#0000cc\">$name</font>>"; +} + +function characterData($parser, $data) +{ + echo "<b>$data</b>"; +} + +function PIHandler($parser, $target, $data) +{ + switch (strtolower($target)) { + case "php": + global $parser_file; + // If the parsed document is "trusted", we say it is safe + // to execute PHP code inside it. If not, display the code + // instead. + if (trustedFile($parser_file[$parser])) { + eval($data); + } else { + printf("Untrusted PHP code: <i>%s</i>", + htmlspecialchars($data)); + } + break; + } +} + +function defaultHandler($parser, $data) +{ + if (substr($data, 0, 1) == "&" && substr($data, -1, 1) == ";") { + printf('<font color="#aa00aa">%s</font>', + htmlspecialchars($data)); + } else { + printf('<font size="-1">%s</font>', + htmlspecialchars($data)); + } +} + +function externalEntityRefHandler($parser, $openEntityNames, $base, $systemId, + $publicId) { + if ($systemId) { + if (!list($parser, $fp) = new_xml_parser($systemId)) { + printf("Could not open entity %s at %s\n", $openEntityNames, + $systemId); + return false; + } + while ($data = fread($fp, 4096)) { + if (!xml_parse($parser, $data, feof($fp))) { + printf("XML error: %s at line %d while parsing entity %s\n", + xml_error_string(xml_get_error_code($parser)), + xml_get_current_line_number($parser), $openEntityNames); + xml_parser_free($parser); + return false; + } + } + xml_parser_free($parser); + return true; + } + return false; +} + +function new_xml_parser($file) +{ + global $parser_file; + + $xml_parser = xml_parser_create(); + xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 1); + xml_set_element_handler($xml_parser, "startElement", "endElement"); + xml_set_character_data_handler($xml_parser, "characterData"); + xml_set_processing_instruction_handler($xml_parser, "PIHandler"); + xml_set_default_handler($xml_parser, "defaultHandler"); + xml_set_external_entity_ref_handler($xml_parser, "externalEntityRefHandler"); + + if (!($fp = @fopen($file, "r"))) { + return false; + } + if (!is_array($parser_file)) { + settype($parser_file, "array"); + } + $parser_file[$xml_parser] = $file; + return array($xml_parser, $fp); +} + +if (!(list($xml_parser, $fp) = new_xml_parser($file))) { + die("could not open XML input"); +} + +echo "<pre>"; +while ($data = fread($fp, 4096)) { + if (!xml_parse($xml_parser, $data, feof($fp))) { + die(sprintf("XML error: %s at line %d\n", + xml_error_string(xml_get_error_code($xml_parser)), + xml_get_current_line_number($xml_parser))); + } +} +echo "</pre>"; +echo "parse complete\n"; +xml_parser_free($xml_parser); + +?> +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title>xmltest.xml</title> + <programlisting role="xml"> +<![CDATA[ +<?xml version='1.0'?> +<!DOCTYPE chapter SYSTEM "/just/a/test.dtd" [ +<!ENTITY plainEntity "FOO entity"> +<!ENTITY systemEntity SYSTEM "xmltest2.xml"> +]> +<chapter> + <TITLE>Title &plainEntity;</TITLE> + <para> + <informaltable> + <tgroup cols="3"> + <tbody> + <row><entry>a1</entry><entry morerows="1">b1</entry><entry>c1</entry></row> + <row><entry>a2</entry><entry>c2</entry></row> + <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row> + </tbody> + </tgroup> + </informaltable> + </para> + &systemEntity; + <section id="about"> + <title>About this Document</title> + <para> + <!-- this is a comment --> + <?php echo 'Hi! This is PHP version ' . phpversion(); ?> + </para> + </section> +</chapter> +]]> + </programlisting> + </example> + </para> + <para> + This file is included from <filename>xmltest.xml</filename>: + <example> + <title>xmltest2.xml</title> + <programlisting role="xml"> +<![CDATA[ +<?xml version="1.0"?> +<!DOCTYPE foo [ +<!ENTITY testEnt "test entity"> +]> +<foo> + <element attrib="value"/> + &testEnt; + <?php echo "This is some more PHP code being executed."; ?> +</foo> +]]> + </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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/setup.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/setup.xml diff -u /dev/null phpdoc/en/reference/xml/setup.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/setup.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,75 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> + +<chapter xml:id="xml.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.setup; + + <!-- {{{ Requirements --> + <section xml:id="xml.requirements"> + &reftitle.required; + <para> + This extension uses an <productname>expat compat layer</productname> by + default. It can use also <productname>expat</productname>, which can + be found at <link xlink:href="&url.expat;">&url.expat;</link>. The + Makefile that comes with expat does not build a library by + default, you can use this make rule for that: + <programlisting role="makefile"> +<![CDATA[ +libexpat.a: $(OBJS) + ar -rc $@ $(OBJS) + ranlib $@ +]]> + </programlisting> + A source RPM package of expat can be found at <link + xlink:href="&url.expat.rpm;">&url.expat.rpm;</link>. + </para> + </section> + <!-- }}} --> + + <!-- {{{ Installation --> + &reference.xml.configure; + <!-- }}} --> + + <!-- {{{ Configuration --> + <section xml:id="xml.configuration"> + &reftitle.runtime; + &no.config; + </section> + <!-- }}} --> + + <!-- {{{ Resources --> + <section xml:id="xml.resources"> + &reftitle.resources; + <para> + The <literal>xml</literal> resource as returned by + <function>xml_parser_create</function> and + <function>xml_parser_create_ns</function> references an xml + parser instance to be used with the functions provided by this + extension. + </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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/constants.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/xml/constants.xml diff -u phpdoc/en/reference/xml/constants.xml:1.3 phpdoc/en/reference/xml/constants.xml:1.4 --- phpdoc/en/reference/xml/constants.xml:1.3 Wed Jun 20 22:25:36 2007 +++ phpdoc/en/reference/xml/constants.xml Sun Dec 23 22:39:46 2007 @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> -<section xml:id="xml.constants" xmlns="http://docbook.org/ns/docbook"> +<!-- $Revision: 1.4 $ --> +<appendix xml:id="xml.constants" xmlns="http://docbook.org/ns/docbook"> &reftitle.constants; &extension.constants; <variablelist> @@ -291,7 +291,7 @@ </listitem> </varlistentry> </variablelist> -</section> +</appendix> <!-- Keep this comment at the end of the file Local variables: http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/reference.xml?r1=1.22&r2=1.23&diff_format=u Index: phpdoc/en/reference/xml/reference.xml diff -u phpdoc/en/reference/xml/reference.xml:1.22 phpdoc/en/reference/xml/reference.xml:1.23 --- phpdoc/en/reference/xml/reference.xml:1.22 Mon Dec 10 17:06:11 2007 +++ phpdoc/en/reference/xml/reference.xml Sun Dec 23 22:39:46 2007 @@ -1,606 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.22 $ --> -<!-- Purpose: xml --> -<!-- Membership: bundled, external --> +<!-- $Revision: 1.23 $ --> - <reference xml:id="ref.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> - <title>XML Parser Functions</title> - <titleabbrev>XML</titleabbrev> +<reference xml:id="ref.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>XML Parser &Functions;</title> - <partintro> + &reference.xml.entities.functions; - <section xml:id="xml.intro"> - &reftitle.intro; - <para> - XML (eXtensible Markup Language) is a data format for structured - document interchange on the Web. It is a standard defined by - The World Wide Web consortium (W3C). Information about XML and - related technologies can be found at <link - xlink:href="&url.xml;">&url.xml;</link>. - </para> - <para> - This PHP extension implements support for James Clark's - <productname>expat</productname> in PHP. This toolkit lets you - parse, but not validate, XML documents. It supports three - source <link linkend="xml.encoding">character encodings</link> - also provided by PHP: <literal>US-ASCII</literal>, - <literal>ISO-8859-1</literal> and <literal>UTF-8</literal>. - <literal>UTF-16</literal> is not supported. - </para> - <para> - This extension lets you <link - linkend="function.xml-parser-create">create XML parsers</link> - and then define <emphasis>handlers</emphasis> for different XML - events. Each XML parser also has a few <link - linkend="function.xml-parser-set-option">parameters</link> you - can adjust. - </para> - </section> +</reference> - <section xml:id="xml.requirements"> - &reftitle.required; - <para> - This extension uses an <productname>expat compat layer</productname> by - default. It can use also <productname>expat</productname>, which can - be found at <link xlink:href="&url.expat;">&url.expat;</link>. The - Makefile that comes with expat does not build a library by - default, you can use this make rule for that: - <programlisting role="makefile"> -<![CDATA[ -libexpat.a: $(OBJS) - ar -rc $@ $(OBJS) - ranlib $@ -]]> - </programlisting> - A source RPM package of expat can be found at <link - xlink:href="&url.expat.rpm;">&url.expat.rpm;</link>. - </para> - </section> - - &reference.xml.configure; - - <section xml:id="xml.configuration"> - &reftitle.runtime; - &no.config; - </section> - - <section xml:id="xml.resources"> - &reftitle.resources; - <section xml:id="xml.resources.xml"> - <title><literal>xml</literal></title> - <para> - The <literal>xml</literal> resource as returned by - <function>xml_parser_create</function> and - <function>xml_parser_create_ns</function> references an xml - parser instance to be used with the functions provided by this - extension. - </para> - </section> - </section> - - &reference.xml.constants; - - <section xml:id="xml.eventhandlers"> - <title>Event Handlers</title> - <para> - The XML event handlers defined are: - <table> - <title>Supported XML handlers</title> - <tgroup cols="2"> - <thead> - <row> - <entry>PHP function to set handler</entry> - <entry>Event description</entry> - </row> - </thead> - <tbody> - <row> - <entry><function>xml_set_element_handler</function></entry> - <entry> - Element events are issued whenever the XML parser - encounters start or end tags. There are separate handlers - for start tags and end tags. - </entry> - </row> - <row> - <entry> - <function>xml_set_character_data_handler</function> - </entry> - <entry> - Character data is roughly all the non-markup contents of - XML documents, including whitespace between tags. Note - that the XML parser does not add or remove any whitespace, - it is up to the application (you) to decide whether - whitespace is significant. - </entry> - </row> - <row> - <entry> - <function>xml_set_processing_instruction_handler</function> - </entry> - <entry> - PHP programmers should be familiar with processing - instructions (PIs) already. <?php ?> is a processing - instruction, where <replaceable>php</replaceable> is called - the "PI target". The handling of these are - application-specific, except that all PI targets starting - with "XML" are reserved. - </entry> - </row> - <row> - <entry><function>xml_set_default_handler</function></entry> - <entry> - What goes not to another handler goes to the default - handler. You will get things like the XML and document - type declarations in the default handler. - </entry> - </row> - <row> - <entry> - <function>xml_set_unparsed_entity_decl_handler</function> - </entry> - <entry> - This handler will be called for declaration of an unparsed - (NDATA) entity. - </entry> - </row> - <row> - <entry> - <function>xml_set_notation_decl_handler</function> - </entry> - <entry> - This handler is called for declaration of a notation. - </entry> - </row> - <row> - <entry> - <function>xml_set_external_entity_ref_handler</function> - </entry> - <entry> - This handler is called when the XML parser finds a - reference to an external parsed general entity. This can - be a reference to a file or URL, for example. See <link - linkend="example.xml-external-entity">the external entity - example</link> for a demonstration. - </entry> - </row> - </tbody> - </tgroup> - </table> - </para> - </section> - - <section xml:id="xml.case-folding"> - <title>Case Folding</title> - <para> - The element handler functions may get their element names - <glossterm>case-folded</glossterm>. Case-folding is defined by - the XML standard as "a process applied to a sequence of - characters, in which those identified as non-uppercase are - replaced by their uppercase equivalents". In other words, when - it comes to XML, case-folding simply means uppercasing. - </para> - <para> - By default, all the element names that are passed to the handler - functions are case-folded. This behaviour can be queried and - controlled per XML parser with the - <function>xml_parser_get_option</function> and - <function>xml_parser_set_option</function> functions, - respectively. - </para> - </section> - - <section xml:id="xml.error-codes"> - <title>Error Codes</title> - <para> - The following constants are defined for XML error codes (as - returned by <function>xml_parse</function>): - <simplelist> - <member>XML_ERROR_NONE</member> - <member>XML_ERROR_NO_MEMORY</member> - <member>XML_ERROR_SYNTAX</member> - <member>XML_ERROR_NO_ELEMENTS</member> - <member>XML_ERROR_INVALID_TOKEN</member> - <member>XML_ERROR_UNCLOSED_TOKEN</member> - <member>XML_ERROR_PARTIAL_CHAR</member> - <member>XML_ERROR_TAG_MISMATCH</member> - <member>XML_ERROR_DUPLICATE_ATTRIBUTE</member> - <member>XML_ERROR_JUNK_AFTER_DOC_ELEMENT</member> - <member>XML_ERROR_PARAM_ENTITY_REF</member> - <member>XML_ERROR_UNDEFINED_ENTITY</member> - <member>XML_ERROR_RECURSIVE_ENTITY_REF</member> - <member>XML_ERROR_ASYNC_ENTITY</member> - <member>XML_ERROR_BAD_CHAR_REF</member> - <member>XML_ERROR_BINARY_ENTITY_REF</member> - <member>XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF</member> - <member>XML_ERROR_MISPLACED_XML_PI</member> - <member>XML_ERROR_UNKNOWN_ENCODING</member> - <member>XML_ERROR_INCORRECT_ENCODING</member> - <member>XML_ERROR_UNCLOSED_CDATA_SECTION</member> - <member>XML_ERROR_EXTERNAL_ENTITY_HANDLING</member> - </simplelist> - </para> - </section> - - <section xml:id="xml.encoding"> - <title>Character Encoding</title> - <para> - PHP's XML extension supports the <link - xlink:href="&url.unicode;">Unicode</link> character set through - different <glossterm>character encoding</glossterm>s. There are - two types of character encodings, <glossterm>source - encoding</glossterm> and <glossterm>target encoding</glossterm>. - PHP's internal representation of the document is always encoded - with <literal>UTF-8</literal>. - </para> - <para> - Source encoding is done when an XML document is <link - linkend="function.xml-parse">parsed</link>. Upon <link - linkend="function.xml-parser-create">creating an XML - parser</link>, a source encoding can be specified (this encoding - can not be changed later in the XML parser's lifetime). The - supported source encodings are <literal>ISO-8859-1</literal>, - <literal>US-ASCII</literal> and <literal>UTF-8</literal>. The - former two are single-byte encodings, which means that each - character is represented by a single byte. - <literal>UTF-8</literal> can encode characters composed by a - variable number of bits (up to 21) in one to four bytes. The - default source encoding used by PHP is - <literal>ISO-8859-1</literal>. - </para> - <para> - Target encoding is done when PHP passes data to XML handler - functions. When an XML parser is created, the target encoding - is set to the same as the source encoding, but this may be - changed at any point. The target encoding will affect character - data as well as tag names and processing instruction targets. - </para> - <para> - If the XML parser encounters characters outside the range that - its source encoding is capable of representing, it will return - an error. - </para> - <para> - If PHP encounters characters in the parsed XML document that can - not be represented in the chosen target encoding, the problem - characters will be "demoted". Currently, this means that such - characters are replaced by a question mark. - </para> - </section> - - <section xml:id="xml.examples"> - &reftitle.examples; - <para> - Here are some example PHP scripts parsing XML documents. - </para> - <section xml:id="example.xml-structure"> - <title>XML Element Structure Example</title> - <para> - This first example displays the structure of the start elements in - a document with indentation. - <example> - <title>Show XML Element Structure</title> - <programlisting role="php"> -<![CDATA[ -<?php -$file = "data.xml"; -$depth = array(); - -function startElement($parser, $name, $attrs) -{ - global $depth; - for ($i = 0; $i < $depth[$parser]; $i++) { - echo " "; - } - echo "$name\n"; - $depth[$parser]++; -} - -function endElement($parser, $name) -{ - global $depth; - $depth[$parser]--; -} - -$xml_parser = xml_parser_create(); -xml_set_element_handler($xml_parser, "startElement", "endElement"); -if (!($fp = fopen($file, "r"))) { - die("could not open XML input"); -} - -while ($data = fread($fp, 4096)) { - if (!xml_parse($xml_parser, $data, feof($fp))) { - die(sprintf("XML error: %s at line %d", - xml_error_string(xml_get_error_code($xml_parser)), - xml_get_current_line_number($xml_parser))); - } -} -xml_parser_free($xml_parser); -?> -]]> - </programlisting> - </example> - </para> - </section> - - <section xml:id="example.xml-map-tags"> - <title>XML Tag Mapping Example</title> - <para> - <example> - <title>Map XML to HTML</title> - <para> - This example maps tags in an XML document directly to HTML - tags. Elements not found in the "map array" are ignored. Of - course, this example will only work with a specific XML - document type. - </para> - <para> - <programlisting role="php"> -<![CDATA[ -<?php -$file = "data.xml"; -$map_array = array( - "BOLD" => "B", - "EMPHASIS" => "I", - "LITERAL" => "TT" -); - -function startElement($parser, $name, $attrs) -{ - global $map_array; - if (isset($map_array[$name])) { - echo "<$map_array[$name]>"; - } -} - -function endElement($parser, $name) -{ - global $map_array; - if (isset($map_array[$name])) { - echo "</$map_array[$name]>"; - } -} - -function characterData($parser, $data) -{ - echo $data; -} - -$xml_parser = xml_parser_create(); -// use case-folding so we are sure to find the tag in $map_array -xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, true); -xml_set_element_handler($xml_parser, "startElement", "endElement"); -xml_set_character_data_handler($xml_parser, "characterData"); -if (!($fp = fopen($file, "r"))) { - die("could not open XML input"); -} - -while ($data = fread($fp, 4096)) { - if (!xml_parse($xml_parser, $data, feof($fp))) { - die(sprintf("XML error: %s at line %d", - xml_error_string(xml_get_error_code($xml_parser)), - xml_get_current_line_number($xml_parser))); - } -} -xml_parser_free($xml_parser); -?> -]]> - </programlisting> - </para> - </example> - </para> - </section> - - <section xml:id="example.xml-external-entity"> - <title>XML External Entity Example</title> - <para> - This example highlights XML code. It illustrates how to use an - external entity reference handler to include and parse other - documents, as well as how PIs can be processed, and a way of - determining "trust" for PIs containing code. - </para> - <para> - XML documents that can be used for this example are found below - the example (<filename>xmltest.xml</filename> and - <filename>xmltest2.xml</filename>.) - </para> - <para> - <example> - <title>External Entity Example</title> - <programlisting role="php"> -<![CDATA[ -<?php -$file = "xmltest.xml"; - -function trustedFile($file) -{ - // only trust local files owned by ourselves - if (!eregi("^([a-z]+)://", $file) - && fileowner($file) == getmyuid()) { - return true; - } - return false; -} - -function startElement($parser, $name, $attribs) -{ - echo "<<font color=\"#0000cc\">$name</font>"; - if (count($attribs)) { - foreach ($attribs as $k => $v) { - echo " <font color=\"#009900\">$k</font>=\"<font - color=\"#990000\">$v</font>\""; - } - } - echo ">"; -} - -function endElement($parser, $name) -{ - echo "</<font color=\"#0000cc\">$name</font>>"; -} - -function characterData($parser, $data) -{ - echo "<b>$data</b>"; -} - -function PIHandler($parser, $target, $data) -{ - switch (strtolower($target)) { - case "php": - global $parser_file; - // If the parsed document is "trusted", we say it is safe - // to execute PHP code inside it. If not, display the code - // instead. - if (trustedFile($parser_file[$parser])) { - eval($data); - } else { - printf("Untrusted PHP code: <i>%s</i>", - htmlspecialchars($data)); - } - break; - } -} - -function defaultHandler($parser, $data) -{ - if (substr($data, 0, 1) == "&" && substr($data, -1, 1) == ";") { - printf('<font color="#aa00aa">%s</font>', - htmlspecialchars($data)); - } else { - printf('<font size="-1">%s</font>', - htmlspecialchars($data)); - } -} - -function externalEntityRefHandler($parser, $openEntityNames, $base, $systemId, - $publicId) { - if ($systemId) { - if (!list($parser, $fp) = new_xml_parser($systemId)) { - printf("Could not open entity %s at %s\n", $openEntityNames, - $systemId); - return false; - } - while ($data = fread($fp, 4096)) { - if (!xml_parse($parser, $data, feof($fp))) { - printf("XML error: %s at line %d while parsing entity %s\n", - xml_error_string(xml_get_error_code($parser)), - xml_get_current_line_number($parser), $openEntityNames); - xml_parser_free($parser); - return false; - } - } - xml_parser_free($parser); - return true; - } - return false; -} - -function new_xml_parser($file) -{ - global $parser_file; - - $xml_parser = xml_parser_create(); - xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 1); - xml_set_element_handler($xml_parser, "startElement", "endElement"); - xml_set_character_data_handler($xml_parser, "characterData"); - xml_set_processing_instruction_handler($xml_parser, "PIHandler"); - xml_set_default_handler($xml_parser, "defaultHandler"); - xml_set_external_entity_ref_handler($xml_parser, "externalEntityRefHandler"); - - if (!($fp = @fopen($file, "r"))) { - return false; - } - if (!is_array($parser_file)) { - settype($parser_file, "array"); - } - $parser_file[$xml_parser] = $file; - return array($xml_parser, $fp); -} - -if (!(list($xml_parser, $fp) = new_xml_parser($file))) { - die("could not open XML input"); -} - -echo "<pre>"; -while ($data = fread($fp, 4096)) { - if (!xml_parse($xml_parser, $data, feof($fp))) { - die(sprintf("XML error: %s at line %d\n", - xml_error_string(xml_get_error_code($xml_parser)), - xml_get_current_line_number($xml_parser))); - } -} -echo "</pre>"; -echo "parse complete\n"; -xml_parser_free($xml_parser); - -?> -]]> - </programlisting> - </example> - </para> - <para> - <example> - <title>xmltest.xml</title> - <programlisting role="xml"> -<![CDATA[ -<?xml version='1.0'?> -<!DOCTYPE chapter SYSTEM "/just/a/test.dtd" [ -<!ENTITY plainEntity "FOO entity"> -<!ENTITY systemEntity SYSTEM "xmltest2.xml"> -]> -<chapter> - <TITLE>Title &plainEntity;</TITLE> - <para> - <informaltable> - <tgroup cols="3"> - <tbody> - <row><entry>a1</entry><entry morerows="1">b1</entry><entry>c1</entry></row> - <row><entry>a2</entry><entry>c2</entry></row> - <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row> - </tbody> - </tgroup> - </informaltable> - </para> - &systemEntity; - <section id="about"> - <title>About this Document</title> - <para> - <!-- this is a comment --> - <?php echo 'Hi! This is PHP version ' . phpversion(); ?> - </para> - </section> -</chapter> -]]> - </programlisting> - </example> - </para> - <para> - This file is included from <filename>xmltest.xml</filename>: - <example> - <title>xmltest2.xml</title> - <programlisting role="xml"> -<![CDATA[ -<?xml version="1.0"?> -<!DOCTYPE foo [ -<!ENTITY testEnt "test entity"> -]> -<foo> - <element attrib="value"/> - &testEnt; - <?php echo "This is some more PHP code being executed."; ?> -</foo> -]]> - </programlisting> - </example> - </para> - </section> - </section> - </partintro> - -&reference.xml.entities.functions; - - </reference> <!-- Keep this comment at the end of the file Local variables: mode: sgml
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/book.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/book.xml diff -u /dev/null phpdoc/en/reference/xml/book.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/book.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<!-- Purpose: xml --> +<!-- Membership: bundled, external --> + +<book xml:id="book.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>XML Parser</title> + + <!-- {{{ preface --> + <preface xml:id="intro.xml"> + &reftitle.intro; + <para> + XML (eXtensible Markup Language) is a data format for structured + document interchange on the Web. It is a standard defined by + The World Wide Web consortium (W3C). Information about XML and + related technologies can be found at <link + xlink:href="&url.xml;">&url.xml;</link>. + </para> + <para> + This PHP extension implements support for James Clark's + <productname>expat</productname> in PHP. This toolkit lets you + parse, but not validate, XML documents. It supports three + source <link linkend="xml.encoding">character encodings</link> + also provided by PHP: <literal>US-ASCII</literal>, + <literal>ISO-8859-1</literal> and <literal>UTF-8</literal>. + <literal>UTF-16</literal> is not supported. + </para> + <para> + This extension lets you <link + linkend="function.xml-parser-create">create XML parsers</link> + and then define <emphasis>handlers</emphasis> for different XML + events. Each XML parser also has a few <link + linkend="function.xml-parser-set-option">parameters</link> you + can adjust. + </para> + </preface> + <!-- }}} --> + + &reference.xml.setup; + &reference.xml.constants; + &reference.xml.eventhandlers; + &reference.xml.case-folding; + &reference.xml.error-codes; + &reference.xml.encoding; + &reference.xml.examples; + &reference.xml.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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/case-folding.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/case-folding.xml diff -u /dev/null phpdoc/en/reference/xml/case-folding.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/case-folding.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<article xml:id="xml.case-folding" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Case Folding</title> + <para> + The element handler functions may get their element names + <glossterm>case-folded</glossterm>. Case-folding is defined by + the XML standard as "a process applied to a sequence of + characters, in which those identified as non-uppercase are + replaced by their uppercase equivalents". In other words, when + it comes to XML, case-folding simply means uppercasing. + </para> + <para> + By default, all the element names that are passed to the handler + functions are case-folded. This behaviour can be queried and + controlled per XML parser with the + <function>xml_parser_get_option</function> and + <function>xml_parser_set_option</function> functions, + respectively. + </para> +</article> + +<!-- 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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/encoding.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/encoding.xml diff -u /dev/null phpdoc/en/reference/xml/encoding.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/encoding.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<article xml:id="xml.encoding" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Character Encoding</title> + <para> + PHP's XML extension supports the <link + xlink:href="&url.unicode;">Unicode</link> character set through + different <glossterm>character encoding</glossterm>s. There are + two types of character encodings, <glossterm>source + encoding</glossterm> and <glossterm>target encoding</glossterm>. + PHP's internal representation of the document is always encoded + with <literal>UTF-8</literal>. + </para> + <para> + Source encoding is done when an XML document is <link + linkend="function.xml-parse">parsed</link>. Upon <link + linkend="function.xml-parser-create">creating an XML + parser</link>, a source encoding can be specified (this encoding + can not be changed later in the XML parser's lifetime). The + supported source encodings are <literal>ISO-8859-1</literal>, + <literal>US-ASCII</literal> and <literal>UTF-8</literal>. The + former two are single-byte encodings, which means that each + character is represented by a single byte. + <literal>UTF-8</literal> can encode characters composed by a + variable number of bits (up to 21) in one to four bytes. The + default source encoding used by PHP is + <literal>ISO-8859-1</literal>. + </para> + <para> + Target encoding is done when PHP passes data to XML handler + functions. When an XML parser is created, the target encoding + is set to the same as the source encoding, but this may be + changed at any point. The target encoding will affect character + data as well as tag names and processing instruction targets. + </para> + <para> + If the XML parser encounters characters outside the range that + its source encoding is capable of representing, it will return + an error. + </para> + <para> + If PHP encounters characters in the parsed XML document that can + not be represented in the chosen target encoding, the problem + characters will be "demoted". Currently, this means that such + characters are replaced by a question mark. + </para> +</article> + +<!-- 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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/error-codes.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/error-codes.xml diff -u /dev/null phpdoc/en/reference/xml/error-codes.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/error-codes.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<article xml:id="xml.error-codes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Error Codes</title> + <para> + The following constants are defined for XML error codes (as + returned by <function>xml_parse</function>): + <simplelist> + <member>XML_ERROR_NONE</member> + <member>XML_ERROR_NO_MEMORY</member> + <member>XML_ERROR_SYNTAX</member> + <member>XML_ERROR_NO_ELEMENTS</member> + <member>XML_ERROR_INVALID_TOKEN</member> + <member>XML_ERROR_UNCLOSED_TOKEN</member> + <member>XML_ERROR_PARTIAL_CHAR</member> + <member>XML_ERROR_TAG_MISMATCH</member> + <member>XML_ERROR_DUPLICATE_ATTRIBUTE</member> + <member>XML_ERROR_JUNK_AFTER_DOC_ELEMENT</member> + <member>XML_ERROR_PARAM_ENTITY_REF</member> + <member>XML_ERROR_UNDEFINED_ENTITY</member> + <member>XML_ERROR_RECURSIVE_ENTITY_REF</member> + <member>XML_ERROR_ASYNC_ENTITY</member> + <member>XML_ERROR_BAD_CHAR_REF</member> + <member>XML_ERROR_BINARY_ENTITY_REF</member> + <member>XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF</member> + <member>XML_ERROR_MISPLACED_XML_PI</member> + <member>XML_ERROR_UNKNOWN_ENCODING</member> + <member>XML_ERROR_INCORRECT_ENCODING</member> + <member>XML_ERROR_UNCLOSED_CDATA_SECTION</member> + <member>XML_ERROR_EXTERNAL_ENTITY_HANDLING</member> + </simplelist> + </para> +</article> + +<!-- 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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/eventhandlers.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/eventhandlers.xml diff -u /dev/null phpdoc/en/reference/xml/eventhandlers.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/eventhandlers.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<article xml:id="xml.eventhandlers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Event Handlers</title> + <para> + The XML event handlers defined are: + <table> + <title>Supported XML handlers</title> + <tgroup cols="2"> + <thead> + <row> + <entry>PHP function to set handler</entry> + <entry>Event description</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>xml_set_element_handler</function></entry> + <entry> + Element events are issued whenever the XML parser + encounters start or end tags. There are separate handlers + for start tags and end tags. + </entry> + </row> + <row> + <entry> + <function>xml_set_character_data_handler</function> + </entry> + <entry> + Character data is roughly all the non-markup contents of + XML documents, including whitespace between tags. Note + that the XML parser does not add or remove any whitespace, + it is up to the application (you) to decide whether + whitespace is significant. + </entry> + </row> + <row> + <entry> + <function>xml_set_processing_instruction_handler</function> + </entry> + <entry> + PHP programmers should be familiar with processing + instructions (PIs) already. <?php ?> is a processing + instruction, where <replaceable>php</replaceable> is called + the "PI target". The handling of these are + application-specific, except that all PI targets starting + with "XML" are reserved. + </entry> + </row> + <row> + <entry><function>xml_set_default_handler</function></entry> + <entry> + What goes not to another handler goes to the default + handler. You will get things like the XML and document + type declarations in the default handler. + </entry> + </row> + <row> + <entry> + <function>xml_set_unparsed_entity_decl_handler</function> + </entry> + <entry> + This handler will be called for declaration of an unparsed + (NDATA) entity. + </entry> + </row> + <row> + <entry> + <function>xml_set_notation_decl_handler</function> + </entry> + <entry> + This handler is called for declaration of a notation. + </entry> + </row> + <row> + <entry> + <function>xml_set_external_entity_ref_handler</function> + </entry> + <entry> + This handler is called when the XML parser finds a + reference to an external parsed general entity. This can + be a reference to a file or URL, for example. See <link + linkend="example.xml-external-entity">the external entity + example</link> for a demonstration. + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> +</article> + +<!-- 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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/examples.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/examples.xml diff -u /dev/null phpdoc/en/reference/xml/examples.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/examples.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,347 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> +<chapter xml:id="xml.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.examples; + <section xml:id="example.xml-structure"> + <title>XML Element Structure Example</title> + <para> + This first example displays the structure of the start elements in + a document with indentation. + <example> + <title>Show XML Element Structure</title> + <programlisting role="php"> +<![CDATA[ +<?php +$file = "data.xml"; +$depth = array(); + +function startElement($parser, $name, $attrs) +{ + global $depth; + for ($i = 0; $i < $depth[$parser]; $i++) { + echo " "; + } + echo "$name\n"; + $depth[$parser]++; +} + +function endElement($parser, $name) +{ + global $depth; + $depth[$parser]--; +} + +$xml_parser = xml_parser_create(); +xml_set_element_handler($xml_parser, "startElement", "endElement"); +if (!($fp = fopen($file, "r"))) { + die("could not open XML input"); +} + +while ($data = fread($fp, 4096)) { + if (!xml_parse($xml_parser, $data, feof($fp))) { + die(sprintf("XML error: %s at line %d", + xml_error_string(xml_get_error_code($xml_parser)), + xml_get_current_line_number($xml_parser))); + } +} +xml_parser_free($xml_parser); +?> +]]> + </programlisting> + </example> + </para> + </section> + + <section xml:id="example.xml-map-tags"> + <title>XML Tag Mapping Example</title> + <para> + <example> + <title>Map XML to HTML</title> + <para> + This example maps tags in an XML document directly to HTML + tags. Elements not found in the "map array" are ignored. Of + course, this example will only work with a specific XML + document type. + </para> + <programlisting role="php"> +<![CDATA[ +<?php +$file = "data.xml"; +$map_array = array( + "BOLD" => "B", + "EMPHASIS" => "I", + "LITERAL" => "TT" +); + +function startElement($parser, $name, $attrs) +{ + global $map_array; + if (isset($map_array[$name])) { + echo "<$map_array[$name]>"; + } +} + +function endElement($parser, $name) +{ + global $map_array; + if (isset($map_array[$name])) { + echo "</$map_array[$name]>"; + } +} + +function characterData($parser, $data) +{ + echo $data; +} + +$xml_parser = xml_parser_create(); +// use case-folding so we are sure to find the tag in $map_array +xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, true); +xml_set_element_handler($xml_parser, "startElement", "endElement"); +xml_set_character_data_handler($xml_parser, "characterData"); +if (!($fp = fopen($file, "r"))) { + die("could not open XML input"); +} + +while ($data = fread($fp, 4096)) { + if (!xml_parse($xml_parser, $data, feof($fp))) { + die(sprintf("XML error: %s at line %d", + xml_error_string(xml_get_error_code($xml_parser)), + xml_get_current_line_number($xml_parser))); + } +} +xml_parser_free($xml_parser); +?> +]]> + </programlisting> + </example> + </para> + </section> + + <section xml:id="example.xml-external-entity"> + <title>XML External Entity Example</title> + <para> + This example highlights XML code. It illustrates how to use an + external entity reference handler to include and parse other + documents, as well as how PIs can be processed, and a way of + determining "trust" for PIs containing code. + </para> + <para> + XML documents that can be used for this example are found below + the example (<filename>xmltest.xml</filename> and + <filename>xmltest2.xml</filename>.) + </para> + <para> + <example> + <title>External Entity Example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$file = "xmltest.xml"; + +function trustedFile($file) +{ + // only trust local files owned by ourselves + if (!eregi("^([a-z]+)://", $file) + && fileowner($file) == getmyuid()) { + return true; + } + return false; +} + +function startElement($parser, $name, $attribs) +{ + echo "<<font color=\"#0000cc\">$name</font>"; + if (count($attribs)) { + foreach ($attribs as $k => $v) { + echo " <font color=\"#009900\">$k</font>=\"<font + color=\"#990000\">$v</font>\""; + } + } + echo ">"; +} + +function endElement($parser, $name) +{ + echo "</<font color=\"#0000cc\">$name</font>>"; +} + +function characterData($parser, $data) +{ + echo "<b>$data</b>"; +} + +function PIHandler($parser, $target, $data) +{ + switch (strtolower($target)) { + case "php": + global $parser_file; + // If the parsed document is "trusted", we say it is safe + // to execute PHP code inside it. If not, display the code + // instead. + if (trustedFile($parser_file[$parser])) { + eval($data); + } else { + printf("Untrusted PHP code: <i>%s</i>", + htmlspecialchars($data)); + } + break; + } +} + +function defaultHandler($parser, $data) +{ + if (substr($data, 0, 1) == "&" && substr($data, -1, 1) == ";") { + printf('<font color="#aa00aa">%s</font>', + htmlspecialchars($data)); + } else { + printf('<font size="-1">%s</font>', + htmlspecialchars($data)); + } +} + +function externalEntityRefHandler($parser, $openEntityNames, $base, $systemId, + $publicId) { + if ($systemId) { + if (!list($parser, $fp) = new_xml_parser($systemId)) { + printf("Could not open entity %s at %s\n", $openEntityNames, + $systemId); + return false; + } + while ($data = fread($fp, 4096)) { + if (!xml_parse($parser, $data, feof($fp))) { + printf("XML error: %s at line %d while parsing entity %s\n", + xml_error_string(xml_get_error_code($parser)), + xml_get_current_line_number($parser), $openEntityNames); + xml_parser_free($parser); + return false; + } + } + xml_parser_free($parser); + return true; + } + return false; +} + +function new_xml_parser($file) +{ + global $parser_file; + + $xml_parser = xml_parser_create(); + xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 1); + xml_set_element_handler($xml_parser, "startElement", "endElement"); + xml_set_character_data_handler($xml_parser, "characterData"); + xml_set_processing_instruction_handler($xml_parser, "PIHandler"); + xml_set_default_handler($xml_parser, "defaultHandler"); + xml_set_external_entity_ref_handler($xml_parser, "externalEntityRefHandler"); + + if (!($fp = @fopen($file, "r"))) { + return false; + } + if (!is_array($parser_file)) { + settype($parser_file, "array"); + } + $parser_file[$xml_parser] = $file; + return array($xml_parser, $fp); +} + +if (!(list($xml_parser, $fp) = new_xml_parser($file))) { + die("could not open XML input"); +} + +echo "<pre>"; +while ($data = fread($fp, 4096)) { + if (!xml_parse($xml_parser, $data, feof($fp))) { + die(sprintf("XML error: %s at line %d\n", + xml_error_string(xml_get_error_code($xml_parser)), + xml_get_current_line_number($xml_parser))); + } +} +echo "</pre>"; +echo "parse complete\n"; +xml_parser_free($xml_parser); + +?> +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title>xmltest.xml</title> + <programlisting role="xml"> +<![CDATA[ +<?xml version='1.0'?> +<!DOCTYPE chapter SYSTEM "/just/a/test.dtd" [ +<!ENTITY plainEntity "FOO entity"> +<!ENTITY systemEntity SYSTEM "xmltest2.xml"> +]> +<chapter> + <TITLE>Title &plainEntity;</TITLE> + <para> + <informaltable> + <tgroup cols="3"> + <tbody> + <row><entry>a1</entry><entry morerows="1">b1</entry><entry>c1</entry></row> + <row><entry>a2</entry><entry>c2</entry></row> + <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row> + </tbody> + </tgroup> + </informaltable> + </para> + &systemEntity; + <section id="about"> + <title>About this Document</title> + <para> + <!-- this is a comment --> + <?php echo 'Hi! This is PHP version ' . phpversion(); ?> + </para> + </section> +</chapter> +]]> + </programlisting> + </example> + </para> + <para> + This file is included from <filename>xmltest.xml</filename>: + <example> + <title>xmltest2.xml</title> + <programlisting role="xml"> +<![CDATA[ +<?xml version="1.0"?> +<!DOCTYPE foo [ +<!ENTITY testEnt "test entity"> +]> +<foo> + <element attrib="value"/> + &testEnt; + <?php echo "This is some more PHP code being executed."; ?> +</foo> +]]> + </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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/setup.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/xml/setup.xml diff -u /dev/null phpdoc/en/reference/xml/setup.xml:1.2 --- /dev/null Sun Dec 23 22:39:46 2007 +++ phpdoc/en/reference/xml/setup.xml Sun Dec 23 22:39:46 2007 @@ -0,0 +1,75 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.2 $ --> + +<chapter xml:id="xml.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.setup; + + <!-- {{{ Requirements --> + <section xml:id="xml.requirements"> + &reftitle.required; + <para> + This extension uses an <productname>expat compat layer</productname> by + default. It can use also <productname>expat</productname>, which can + be found at <link xlink:href="&url.expat;">&url.expat;</link>. The + Makefile that comes with expat does not build a library by + default, you can use this make rule for that: + <programlisting role="makefile"> +<![CDATA[ +libexpat.a: $(OBJS) + ar -rc $@ $(OBJS) + ranlib $@ +]]> + </programlisting> + A source RPM package of expat can be found at <link + xlink:href="&url.expat.rpm;">&url.expat.rpm;</link>. + </para> + </section> + <!-- }}} --> + + <!-- {{{ Installation --> + &reference.xml.configure; + <!-- }}} --> + + <!-- {{{ Configuration --> + <section xml:id="xml.configuration"> + &reftitle.runtime; + &no.config; + </section> + <!-- }}} --> + + <!-- {{{ Resources --> + <section xml:id="xml.resources"> + &reftitle.resources; + <para> + The <literal>xml</literal> resource as returned by + <function>xml_parser_create</function> and + <function>xml_parser_create_ns</function> references an xml + parser instance to be used with the functions provided by this + extension. + </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 +--> + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/constants.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/xml/constants.xml diff -u phpdoc/en/reference/xml/constants.xml:1.3 phpdoc/en/reference/xml/constants.xml:1.4 --- phpdoc/en/reference/xml/constants.xml:1.3 Wed Jun 20 22:25:36 2007 +++ phpdoc/en/reference/xml/constants.xml Sun Dec 23 22:39:46 2007 @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> -<section xml:id="xml.constants" xmlns="http://docbook.org/ns/docbook"> +<!-- $Revision: 1.4 $ --> +<appendix xml:id="xml.constants" xmlns="http://docbook.org/ns/docbook"> &reftitle.constants; &extension.constants; <variablelist> @@ -291,7 +291,7 @@ </listitem> </varlistentry> </variablelist> -</section> +</appendix> <!-- Keep this comment at the end of the file Local variables: http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/xml/reference.xml?r1=1.22&r2=1.23&diff_format=u Index: phpdoc/en/reference/xml/reference.xml diff -u phpdoc/en/reference/xml/reference.xml:1.22 phpdoc/en/reference/xml/reference.xml:1.23 --- phpdoc/en/reference/xml/reference.xml:1.22 Mon Dec 10 17:06:11 2007 +++ phpdoc/en/reference/xml/reference.xml Sun Dec 23 22:39:46 2007 @@ -1,606 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.22 $ --> -<!-- Purpose: xml --> -<!-- Membership: bundled, external --> +<!-- $Revision: 1.23 $ --> - <reference xml:id="ref.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> - <title>XML Parser Functions</title> - <titleabbrev>XML</titleabbrev> +<reference xml:id="ref.xml" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>XML Parser &Functions;</title> - <partintro> + &reference.xml.entities.functions; - <section xml:id="xml.intro"> - &reftitle.intro; - <para> - XML (eXtensible Markup Language) is a data format for structured - document interchange on the Web. It is a standard defined by - The World Wide Web consortium (W3C). Information about XML and - related technologies can be found at <link - xlink:href="&url.xml;">&url.xml;</link>. - </para> - <para> - This PHP extension implements support for James Clark's - <productname>expat</productname> in PHP. This toolkit lets you - parse, but not validate, XML documents. It supports three - source <link linkend="xml.encoding">character encodings</link> - also provided by PHP: <literal>US-ASCII</literal>, - <literal>ISO-8859-1</literal> and <literal>UTF-8</literal>. - <literal>UTF-16</literal> is not supported. - </para> - <para> - This extension lets you <link - linkend="function.xml-parser-create">create XML parsers</link> - and then define <emphasis>handlers</emphasis> for different XML - events. Each XML parser also has a few <link - linkend="function.xml-parser-set-option">parameters</link> you - can adjust. - </para> - </section> +</reference> - <section xml:id="xml.requirements"> - &reftitle.required; - <para> - This extension uses an <productname>expat compat layer</productname> by - default. It can use also <productname>expat</productname>, which can - be found at <link xlink:href="&url.expat;">&url.expat;</link>. The - Makefile that comes with expat does not build a library by - default, you can use this make rule for that: - <programlisting role="makefile"> -<![CDATA[ -libexpat.a: $(OBJS) - ar -rc $@ $(OBJS) - ranlib $@ -]]> - </programlisting> - A source RPM package of expat can be found at <link - xlink:href="&url.expat.rpm;">&url.expat.rpm;</link>. - </para> - </section> - - &reference.xml.configure; - - <section xml:id="xml.configuration"> - &reftitle.runtime; - &no.config; - </section> - - <section xml:id="xml.resources"> - &reftitle.resources; - <section xml:id="xml.resources.xml"> - <title><literal>xml</literal></title> - <para> - The <literal>xml</literal> resource as returned by - <function>xml_parser_create</function> and - <function>xml_parser_create_ns</function> references an xml - parser instance to be used with the functions provided by this - extension. - </para> - </section> - </section> - - &reference.xml.constants; - - <section xml:id="xml.eventhandlers"> - <title>Event Handlers</title> - <para> - The XML event handlers defined are: - <table> - <title>Supported XML handlers</title> - <tgroup cols="2"> - <thead> - <row> - <entry>PHP function to set handler</entry> - <entry>Event description</entry> - </row> - </thead> - <tbody> - <row> - <entry><function>xml_set_element_handler</function></entry> - <entry> - Element events are issued whenever the XML parser - encounters start or end tags. There are separate handlers - for start tags and end tags. - </entry> - </row> - <row> - <entry> - <function>xml_set_character_data_handler</function> - </entry> - <entry> - Character data is roughly all the non-markup contents of - XML documents, including whitespace between tags. Note - that the XML parser does not add or remove any whitespace, - it is up to the application (you) to decide whether - whitespace is significant. - </entry> - </row> - <row> - <entry> - <function>xml_set_processing_instruction_handler</function> - </entry> - <entry> - PHP programmers should be familiar with processing - instructions (PIs) already. <?php ?> is a processing - instruction, where <replaceable>php</replaceable> is called - the "PI target". The handling of these are - application-specific, except that all PI targets starting - with "XML" are reserved. - </entry> - </row> - <row> - <entry><function>xml_set_default_handler</function></entry> - <entry> - What goes not to another handler goes to the default - handler. You will get things like the XML and document - type declarations in the default handler. - </entry> - </row> - <row> - <entry> - <function>xml_set_unparsed_entity_decl_handler</function> - </entry> - <entry> - This handler will be called for declaration of an unparsed - (NDATA) entity. - </entry> - </row> - <row> - <entry> - <function>xml_set_notation_decl_handler</function> - </entry> - <entry> - This handler is called for declaration of a notation. - </entry> - </row> - <row> - <entry> - <function>xml_set_external_entity_ref_handler</function> - </entry> - <entry> - This handler is called when the XML parser finds a - reference to an external parsed general entity. This can - be a reference to a file or URL, for example. See <link - linkend="example.xml-external-entity">the external entity - example</link> for a demonstration. - </entry> - </row> - </tbody> - </tgroup> - </table> - </para> - </section> - - <section xml:id="xml.case-folding"> - <title>Case Folding</title> - <para> - The element handler functions may get their element names - <glossterm>case-folded</glossterm>. Case-folding is defined by - the XML standard as "a process applied to a sequence of - characters, in which those identified as non-uppercase are - replaced by their uppercase equivalents". In other words, when - it comes to XML, case-folding simply means uppercasing. - </para> - <para> - By default, all the element names that are passed to the handler - functions are case-folded. This behaviour can be queried and - controlled per XML parser with the - <function>xml_parser_get_option</function> and - <function>xml_parser_set_option</function> functions, - respectively. - </para> - </section> - - <section xml:id="xml.error-codes"> - <title>Error Codes</title> - <para> - The following constants are defined for XML error codes (as - returned by <function>xml_parse</function>): - <simplelist> - <member>XML_ERROR_NONE</member> - <member>XML_ERROR_NO_MEMORY</member> - <member>XML_ERROR_SYNTAX</member> - <member>XML_ERROR_NO_ELEMENTS</member> - <member>XML_ERROR_INVALID_TOKEN</member> - <member>XML_ERROR_UNCLOSED_TOKEN</member> - <member>XML_ERROR_PARTIAL_CHAR</member> - <member>XML_ERROR_TAG_MISMATCH</member> - <member>XML_ERROR_DUPLICATE_ATTRIBUTE</member> - <member>XML_ERROR_JUNK_AFTER_DOC_ELEMENT</member> - <member>XML_ERROR_PARAM_ENTITY_REF</member> - <member>XML_ERROR_UNDEFINED_ENTITY</member> - <member>XML_ERROR_RECURSIVE_ENTITY_REF</member> - <member>XML_ERROR_ASYNC_ENTITY</member> - <member>XML_ERROR_BAD_CHAR_REF</member> - <member>XML_ERROR_BINARY_ENTITY_REF</member> - <member>XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF</member> - <member>XML_ERROR_MISPLACED_XML_PI</member> - <member>XML_ERROR_UNKNOWN_ENCODING</member> - <member>XML_ERROR_INCORRECT_ENCODING</member> - <member>XML_ERROR_UNCLOSED_CDATA_SECTION</member> - <member>XML_ERROR_EXTERNAL_ENTITY_HANDLING</member> - </simplelist> - </para> - </section> - - <section xml:id="xml.encoding"> - <title>Character Encoding</title> - <para> - PHP's XML extension supports the <link - xlink:href="&url.unicode;">Unicode</link> character set through - different <glossterm>character encoding</glossterm>s. There are - two types of character encodings, <glossterm>source - encoding</glossterm> and <glossterm>target encoding</glossterm>. - PHP's internal representation of the document is always encoded - with <literal>UTF-8</literal>. - </para> - <para> - Source encoding is done when an XML document is <link - linkend="function.xml-parse">parsed</link>. Upon <link - linkend="function.xml-parser-create">creating an XML - parser</link>, a source encoding can be specified (this encoding - can not be changed later in the XML parser's lifetime). The - supported source encodings are <literal>ISO-8859-1</literal>, - <literal>US-ASCII</literal> and <literal>UTF-8</literal>. The - former two are single-byte encodings, which means that each - character is represented by a single byte. - <literal>UTF-8</literal> can encode characters composed by a - variable number of bits (up to 21) in one to four bytes. The - default source encoding used by PHP is - <literal>ISO-8859-1</literal>. - </para> - <para> - Target encoding is done when PHP passes data to XML handler - functions. When an XML parser is created, the target encoding - is set to the same as the source encoding, but this may be - changed at any point. The target encoding will affect character - data as well as tag names and processing instruction targets. - </para> - <para> - If the XML parser encounters characters outside the range that - its source encoding is capable of representing, it will return - an error. - </para> - <para> - If PHP encounters characters in the parsed XML document that can - not be represented in the chosen target encoding, the problem - characters will be "demoted". Currently, this means that such - characters are replaced by a question mark. - </para> - </section> - - <section xml:id="xml.examples"> - &reftitle.examples; - <para> - Here are some example PHP scripts parsing XML documents. - </para> - <section xml:id="example.xml-structure"> - <title>XML Element Structure Example</title> - <para> - This first example displays the structure of the start elements in - a document with indentation. - <example> - <title>Show XML Element Structure</title> - <programlisting role="php"> -<![CDATA[ -<?php -$file = "data.xml"; -$depth = array(); - -function startElement($parser, $name, $attrs) -{ - global $depth; - for ($i = 0; $i < $depth[$parser]; $i++) { - echo " "; - } - echo "$name\n"; - $depth[$parser]++; -} - -function endElement($parser, $name) -{ - global $depth; - $depth[$parser]--; -} - -$xml_parser = xml_parser_create(); -xml_set_element_handler($xml_parser, "startElement", "endElement"); -if (!($fp = fopen($file, "r"))) { - die("could not open XML input"); -} - -while ($data = fread($fp, 4096)) { - if (!xml_parse($xml_parser, $data, feof($fp))) { - die(sprintf("XML error: %s at line %d", - xml_error_string(xml_get_error_code($xml_parser)), - xml_get_current_line_number($xml_parser))); - } -} -xml_parser_free($xml_parser); -?> -]]> - </programlisting> - </example> - </para> - </section> - - <section xml:id="example.xml-map-tags"> - <title>XML Tag Mapping Example</title> - <para> - <example> - <title>Map XML to HTML</title> - <para> - This example maps tags in an XML document directly to HTML - tags. Elements not found in the "map array" are ignored. Of - course, this example will only work with a specific XML - document type. - </para> - <para> - <programlisting role="php"> -<![CDATA[ -<?php -$file = "data.xml"; -$map_array = array( - "BOLD" => "B", - "EMPHASIS" => "I", - "LITERAL" => "TT" -); - -function startElement($parser, $name, $attrs) -{ - global $map_array; - if (isset($map_array[$name])) { - echo "<$map_array[$name]>"; - } -} - -function endElement($parser, $name) -{ - global $map_array; - if (isset($map_array[$name])) { - echo "</$map_array[$name]>"; - } -} - -function characterData($parser, $data) -{ - echo $data; -} - -$xml_parser = xml_parser_create(); -// use case-folding so we are sure to find the tag in $map_array -xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, true); -xml_set_element_handler($xml_parser, "startElement", "endElement"); -xml_set_character_data_handler($xml_parser, "characterData"); -if (!($fp = fopen($file, "r"))) { - die("could not open XML input"); -} - -while ($data = fread($fp, 4096)) { - if (!xml_parse($xml_parser, $data, feof($fp))) { - die(sprintf("XML error: %s at line %d", - xml_error_string(xml_get_error_code($xml_parser)), - xml_get_current_line_number($xml_parser))); - } -} -xml_parser_free($xml_parser); -?> -]]> - </programlisting> - </para> - </example> - </para> - </section> - - <section xml:id="example.xml-external-entity"> - <title>XML External Entity Example</title> - <para> - This example highlights XML code. It illustrates how to use an - external entity reference handler to include and parse other - documents, as well as how PIs can be processed, and a way of - determining "trust" for PIs containing code. - </para> - <para> - XML documents that can be used for this example are found below - the example (<filename>xmltest.xml</filename> and - <filename>xmltest2.xml</filename>.) - </para> - <para> - <example> - <title>External Entity Example</title> - <programlisting role="php"> -<![CDATA[ -<?php -$file = "xmltest.xml"; - -function trustedFile($file) -{ - // only trust local files owned by ourselves - if (!eregi("^([a-z]+)://", $file) - && fileowner($file) == getmyuid()) { - return true; - } - return false; -} - -function startElement($parser, $name, $attribs) -{ - echo "<<font color=\"#0000cc\">$name</font>"; - if (count($attribs)) { - foreach ($attribs as $k => $v) { - echo " <font color=\"#009900\">$k</font>=\"<font - color=\"#990000\">$v</font>\""; - } - } - echo ">"; -} - -function endElement($parser, $name) -{ - echo "</<font color=\"#0000cc\">$name</font>>"; -} - -function characterData($parser, $data) -{ - echo "<b>$data</b>"; -} - -function PIHandler($parser, $target, $data) -{ - switch (strtolower($target)) { - case "php": - global $parser_file; - // If the parsed document is "trusted", we say it is safe - // to execute PHP code inside it. If not, display the code - // instead. - if (trustedFile($parser_file[$parser])) { - eval($data); - } else { - printf("Untrusted PHP code: <i>%s</i>", - htmlspecialchars($data)); - } - break; - } -} - -function defaultHandler($parser, $data) -{ - if (substr($data, 0, 1) == "&" && substr($data, -1, 1) == ";") { - printf('<font color="#aa00aa">%s</font>', - htmlspecialchars($data)); - } else { - printf('<font size="-1">%s</font>', - htmlspecialchars($data)); - } -} - -function externalEntityRefHandler($parser, $openEntityNames, $base, $systemId, - $publicId) { - if ($systemId) { - if (!list($parser, $fp) = new_xml_parser($systemId)) { - printf("Could not open entity %s at %s\n", $openEntityNames, - $systemId); - return false; - } - while ($data = fread($fp, 4096)) { - if (!xml_parse($parser, $data, feof($fp))) { - printf("XML error: %s at line %d while parsing entity %s\n", - xml_error_string(xml_get_error_code($parser)), - xml_get_current_line_number($parser), $openEntityNames); - xml_parser_free($parser); - return false; - } - } - xml_parser_free($parser); - return true; - } - return false; -} - -function new_xml_parser($file) -{ - global $parser_file; - - $xml_parser = xml_parser_create(); - xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 1); - xml_set_element_handler($xml_parser, "startElement", "endElement"); - xml_set_character_data_handler($xml_parser, "characterData"); - xml_set_processing_instruction_handler($xml_parser, "PIHandler"); - xml_set_default_handler($xml_parser, "defaultHandler"); - xml_set_external_entity_ref_handler($xml_parser, "externalEntityRefHandler"); - - if (!($fp = @fopen($file, "r"))) { - return false; - } - if (!is_array($parser_file)) { - settype($parser_file, "array"); - } - $parser_file[$xml_parser] = $file; - return array($xml_parser, $fp); -} - -if (!(list($xml_parser, $fp) = new_xml_parser($file))) { - die("could not open XML input"); -} - -echo "<pre>"; -while ($data = fread($fp, 4096)) { - if (!xml_parse($xml_parser, $data, feof($fp))) { - die(sprintf("XML error: %s at line %d\n", - xml_error_string(xml_get_error_code($xml_parser)), - xml_get_current_line_number($xml_parser))); - } -} -echo "</pre>"; -echo "parse complete\n"; -xml_parser_free($xml_parser); - -?> -]]> - </programlisting> - </example> - </para> - <para> - <example> - <title>xmltest.xml</title> - <programlisting role="xml"> -<![CDATA[ -<?xml version='1.0'?> -<!DOCTYPE chapter SYSTEM "/just/a/test.dtd" [ -<!ENTITY plainEntity "FOO entity"> -<!ENTITY systemEntity SYSTEM "xmltest2.xml"> -]> -<chapter> - <TITLE>Title &plainEntity;</TITLE> - <para> - <informaltable> - <tgroup cols="3"> - <tbody> - <row><entry>a1</entry><entry morerows="1">b1</entry><entry>c1</entry></row> - <row><entry>a2</entry><entry>c2</entry></row> - <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row> - </tbody> - </tgroup> - </informaltable> - </para> - &systemEntity; - <section id="about"> - <title>About this Document</title> - <para> - <!-- this is a comment --> - <?php echo 'Hi! This is PHP version ' . phpversion(); ?> - </para> - </section> -</chapter> -]]> - </programlisting> - </example> - </para> - <para> - This file is included from <filename>xmltest.xml</filename>: - <example> - <title>xmltest2.xml</title> - <programlisting role="xml"> -<![CDATA[ -<?xml version="1.0"?> -<!DOCTYPE foo [ -<!ENTITY testEnt "test entity"> -]> -<foo> - <element attrib="value"/> - &testEnt; - <?php echo "This is some more PHP code being executed."; ?> -</foo> -]]> - </programlisting> - </example> - </para> - </section> - </section> - </partintro> - -&reference.xml.entities.functions; - - </reference> <!-- Keep this comment at the end of the file Local variables: mode: sgml