mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 17:08:54 +00:00
7839d91186
removing the others git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@78562 c90b9560-bf6c-de11-be94-00142212c4b1
2109 lines
67 KiB
XML
2109 lines
67 KiB
XML
<!-- D O N O T E D I T T H I S F I L E ! ! !
|
|
|
|
it is still here for historical reasons only
|
|
(as translators may need to check old revision diffs)
|
|
|
|
if you want to change things documented in this file
|
|
you should now edit the files found under en/reference
|
|
instead -->
|
|
|
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.27 $ -->
|
|
<reference id="ref.xml">
|
|
<title>XML parser functions</title>
|
|
<titleabbrev>XML</titleabbrev>
|
|
|
|
<partintro>
|
|
<sect1 id="xml.partintro">
|
|
<title>Introduction</title>
|
|
<sect2 id="xml.intro">
|
|
<title>About XML</title>
|
|
<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 <ulink
|
|
url="&url.xml;">&url.xml;</ulink>.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="xml.install">
|
|
<title>Installation</title>
|
|
<para>
|
|
This extension uses <productname>expat</productname>, which can
|
|
be found at <ulink url="&url.expat;">&url.expat;</ulink>. 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 <ulink
|
|
url="&url.expat.rpm;">&url.expat.rpm;</ulink>.
|
|
</para>
|
|
<para>
|
|
Note that if you are using Apache-1.3.7 or later, you already
|
|
have the required expat library. Simply configure PHP using
|
|
<option role="configure">--with-xml</option> (without any
|
|
additional path) and it will automatically use the expat library
|
|
built into Apache.
|
|
</para>
|
|
<para>
|
|
On UNIX, run <command>configure</command> with the <option
|
|
role="configure">--with-xml</option> option. The
|
|
<productname>expat</productname> library should be installed
|
|
somewhere your compiler can find it. If you compile PHP as a
|
|
module for Apache 1.3.9 or later, PHP will automatically use the
|
|
bundled <productname>expat</productname> library from Apache.
|
|
You may need to set <envar>CPPFLAGS</envar> and
|
|
<envar>LDFLAGS</envar> in your environment before running
|
|
configure if you have installed expat somewhere exotic.
|
|
</para>
|
|
<para>
|
|
Build PHP. <emphasis>Tada!</emphasis> That should be it.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="xml.about">
|
|
<title>About This Extension</title>
|
|
<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>
|
|
<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>
|
|
</sect2>
|
|
|
|
<sect2 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>
|
|
</sect2>
|
|
|
|
<sect2 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>
|
|
</sect2>
|
|
<sect2 id="xml.encoding">
|
|
<title>Character Encoding</title>
|
|
<para>
|
|
PHP's XML extension supports the <ulink
|
|
url="&url.unicode;">Unicode</ulink> 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>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="xml.examples">
|
|
<title>Some Examples</title>
|
|
<para>
|
|
Here are some example PHP scripts parsing XML documents.
|
|
</para>
|
|
<sect2 id="example.xml-structure">
|
|
<title>XML Element Structure Example</title>
|
|
<para>
|
|
This first example displays the stucture of the start elements in
|
|
a document with indentation.
|
|
<example>
|
|
<title>Show XML Element Structure</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$file = "data.xml";
|
|
$depth = array();
|
|
|
|
function startElement($parser, $name, $attrs) {
|
|
global $depth;
|
|
for ($i = 0; $i < $depth[$parser]; $i++) {
|
|
print " ";
|
|
}
|
|
print "$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>
|
|
</sect2>
|
|
|
|
<sect2 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.
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$file = "data.xml";
|
|
$map_array = array(
|
|
"BOLD" => "B",
|
|
"EMPHASIS" => "I",
|
|
"LITERAL" => "TT"
|
|
);
|
|
|
|
function startElement($parser, $name, $attrs) {
|
|
global $map_array;
|
|
if ($htmltag = $map_array[$name]) {
|
|
print "<$htmltag>";
|
|
}
|
|
}
|
|
|
|
function endElement($parser, $name) {
|
|
global $map_array;
|
|
if ($htmltag = $map_array[$name]) {
|
|
print "</$htmltag>";
|
|
}
|
|
}
|
|
|
|
function characterData($parser, $data) {
|
|
print $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>
|
|
</sect2>
|
|
|
|
<sect2 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[
|
|
$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) {
|
|
print "<<font color=\"#0000cc\">$name</font>";
|
|
if (sizeof($attribs)) {
|
|
while (list($k, $v) = each($attribs)) {
|
|
print " <font color=\"#009900\">$k</font>=\"<font
|
|
color=\"#990000\">$v</font>\"";
|
|
}
|
|
}
|
|
print ">";
|
|
}
|
|
|
|
function endElement($parser, $name) {
|
|
print "</<font color=\"#0000cc\">$name</font>>";
|
|
}
|
|
|
|
function characterData($parser, $data) {
|
|
print "<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");
|
|
}
|
|
|
|
print "<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)));
|
|
}
|
|
}
|
|
print "</pre>";
|
|
print "parse complete\n";
|
|
xml_parser_free($xml_parser);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para id="example.xml-xmltest.xml">
|
|
<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;
|
|
<sect1 id="about">
|
|
<title>About this Document</title>
|
|
<para>
|
|
<!-- this is a comment -->
|
|
<?php print 'Hi! This is PHP version '.phpversion(); ?>
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para id="example.xml-xmltest2.xml">
|
|
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 print "This is some more PHP code being executed."; ?>
|
|
</foo>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</partintro>
|
|
|
|
<refentry id="function.xml-parser-create">
|
|
<refnamediv>
|
|
<refname>xml_parser_create</refname>
|
|
<refpurpose>create an XML parser</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_parser_create</methodname>
|
|
<methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>encoding</parameter> (optional)</term>
|
|
<listitem>
|
|
<para>
|
|
Which character encoding the parser should use. The
|
|
following character encodings are supported:
|
|
<simplelist>
|
|
<member><literal>ISO-8859-1</literal> (default)</member>
|
|
<member><literal>US-ASCII</literal></member>
|
|
<member><literal>UTF-8</literal></member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
This function creates an XML parser and returns a handle for use
|
|
by other XML functions. Returns &false; on
|
|
failure.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-set-object">
|
|
<refnamediv>
|
|
<refname>xml_set_object</refname>
|
|
<refpurpose>Use XML Parser within an object</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>xml_set_object</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>object</type><parameter>&object</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function allows to use <parameter>parser</parameter> inside
|
|
<parameter>object</parameter>. All callback functions could be
|
|
set with <function>xml_set_element_handler</function> etc and
|
|
assumed to be methods of <parameter>object</parameter>.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
class xml {
|
|
var $parser;
|
|
|
|
function xml() {
|
|
$this->parser = xml_parser_create();
|
|
xml_set_object($this->parser,&$this);
|
|
xml_set_element_handler($this->parser,"tag_open","tag_close");
|
|
xml_set_character_data_handler($this->parser,"cdata");
|
|
}
|
|
|
|
function parse($data) {
|
|
xml_parse($this->parser,$data);
|
|
}
|
|
|
|
function tag_open($parser,$tag,$attributes) {
|
|
var_dump($parser,$tag,$attributes);
|
|
}
|
|
|
|
function cdata($parser,$cdata) {
|
|
var_dump($parser,$cdata);
|
|
}
|
|
|
|
function tag_close($parser,$tag) {
|
|
var_dump($parser,$tag);
|
|
}
|
|
|
|
} // end of class xml
|
|
|
|
$xml_parser = new xml();
|
|
$xml_parser->parse("<A ID=\"hallo\">PHP</A>");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-set-element-handler">
|
|
<refnamediv>
|
|
<refname>xml_set_element_handler</refname>
|
|
<refpurpose>set up start and end element handlers</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_set_element_handler</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>startElementHandler</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>endElementHandler</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sets the element handler functions for the XML parser
|
|
<parameter>parser</parameter>.
|
|
<parameter>startElementHandler</parameter> and
|
|
<parameter>endElementHandler</parameter> are strings containing
|
|
the names of functions that must exist when
|
|
<function>xml_parse</function> is called for
|
|
<parameter>parser</parameter>.
|
|
</para>
|
|
<para>
|
|
The function named by <parameter>startElementHandler</parameter>
|
|
must accept three parameters:
|
|
<methodsynopsis>
|
|
<methodname><replaceable>startElementHandler</replaceable></methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>name</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>attribs</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The first parameter, <replaceable>parser</replaceable>, is a
|
|
reference to the XML parser calling the
|
|
handler.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>name</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The second parameter, <parameter>name</parameter>, contains
|
|
the name of the element for which this handler is called. If
|
|
<link linkend="xml.case-folding">case-folding</link> is in
|
|
effect for this parser, the element name will be in uppercase
|
|
letters.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>attribs</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The third parameter, <parameter>attribs</parameter>, contains
|
|
an associative array with the element's attributes (if any).
|
|
The keys of this array are the attribute names, the values
|
|
are the attribute values. Attribute names are <link
|
|
linkend="xml.case-folding">case-folded</link> on the same
|
|
criteria as element names. Attribute values are
|
|
<emphasis>not</emphasis> case-folded.
|
|
</simpara>
|
|
<simpara>
|
|
The original order of the attributes can be retrieved by
|
|
walking through <parameter>attribs</parameter> the normal
|
|
way, using <function>each</function>. The first key in the
|
|
array was the first attribute, and so on.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
The function named by <parameter>endElementHandler</parameter>
|
|
must accept two parameters:
|
|
<methodsynopsis>
|
|
<methodname><replaceable>endElementHandler</replaceable></methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>name</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The first parameter, <replaceable>parser</replaceable>, is a
|
|
reference to the XML parser calling the
|
|
handler.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>name</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The second parameter, <parameter>name</parameter>, contains
|
|
the name of the element for which this handler is called. If
|
|
<link linkend="xml.case-folding">case-folding</link> is in
|
|
effect for this parser, the element name will be in uppercase
|
|
letters.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
If a handler function is set to an empty string, or
|
|
&false;, the handler in question is disabled.
|
|
</para>
|
|
<para>
|
|
&true; is returned if the handlers are set up, &false; if
|
|
<parameter>parser</parameter> is not a parser.
|
|
</para>
|
|
¬e.func-callback;
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-set-character-data-handler">
|
|
<refnamediv>
|
|
<refname>xml_set_character_data_handler</refname>
|
|
<refpurpose>set up character data handler</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_set_character_data_handler</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>handler</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sets the character data handler function for the XML parser
|
|
<parameter>parser</parameter>. <parameter>handler</parameter> is
|
|
a string containing the name of a function that must exist when
|
|
<function>xml_parse</function> is called for
|
|
<parameter>parser</parameter>.</para>
|
|
<para>
|
|
The function named by <parameter>handler</parameter> must accept
|
|
two parameters:
|
|
<methodsynopsis>
|
|
<methodname><replaceable>handler</replaceable></methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>data</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The first parameter, <replaceable>parser</replaceable>, is a
|
|
reference to the XML parser calling the handler.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>data</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The second parameter, <parameter>data</parameter>, contains
|
|
the character data as a string.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
<para>
|
|
If a handler function is set to an empty string, or
|
|
&false;, the handler in question is
|
|
disabled.
|
|
</para>
|
|
<para>
|
|
&true; is returned if the handler is set up, &false; if
|
|
<parameter>parser</parameter> is not a parser.
|
|
</para>
|
|
¬e.func-callback;
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-set-processing-instruction-handler">
|
|
<refnamediv>
|
|
<refname>xml_set_processing_instruction_handler</refname>
|
|
<refpurpose>
|
|
Set up processing instruction (PI) handler
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_set_processing_instruction_handler</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>handler</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sets the processing instruction (PI) handler function for the XML
|
|
parser <parameter>parser</parameter>.
|
|
<parameter>handler</parameter> is a string containing the name of
|
|
a function that must exist when <function>xml_parse</function> is
|
|
called for <parameter>parser</parameter>.
|
|
</para>
|
|
<para>
|
|
A processing instruction has the following format:
|
|
<informalexample>
|
|
<programlisting><?
|
|
<replaceable>target</replaceable>
|
|
<replaceable>data</replaceable>?>
|
|
</programlisting>
|
|
</informalexample>
|
|
You can put PHP code into such a tag, but be aware of one
|
|
limitation: in an XML PI, the PI end tag
|
|
(<literal>?></literal>) can not be quoted, so this character
|
|
sequence should not appear in the PHP code you embed with PIs in
|
|
XML documents. If it does, the rest of the PHP code, as well as
|
|
the "real" PI end tag, will be treated as character data.
|
|
</para>
|
|
<para>
|
|
The function named by <parameter>handler</parameter> must accept
|
|
three parameters:
|
|
<methodsynopsis>
|
|
<methodname><replaceable>handler</replaceable></methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>target</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>data</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term> <listitem><simpara>
|
|
The first parameter, <replaceable>parser</replaceable>, is a
|
|
reference to the XML parser calling the
|
|
handler.</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>target</parameter></term>
|
|
<listitem><simpara>
|
|
The second parameter, <parameter>target</parameter>, contains
|
|
the PI target.</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>data</parameter></term>
|
|
<listitem><simpara>
|
|
The third parameter, <parameter>data</parameter>, contains
|
|
the PI data.</simpara></listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
<para>
|
|
If a handler function is set to an empty string, or
|
|
&false;, the handler in question is disabled.
|
|
</para>
|
|
<para>
|
|
&true; is returned if the handler is set up, &false; if
|
|
<parameter>parser</parameter> is not a parser.
|
|
</para>
|
|
¬e.func-callback;
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-set-default-handler">
|
|
<refnamediv>
|
|
<refname>xml_set_default_handler</refname>
|
|
<refpurpose>set up default handler</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_set_default_handler</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>handler</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sets the default handler function for the XML parser
|
|
<parameter>parser</parameter>. <parameter>handler</parameter> is
|
|
a string containing the name of a function that must exist when
|
|
<function>xml_parse</function> is called for
|
|
<parameter>parser</parameter>.</para>
|
|
<para>
|
|
The function named by <parameter>handler</parameter> must accept
|
|
two parameters:
|
|
<methodsynopsis>
|
|
<methodname><replaceable>handler</replaceable></methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>data</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>parser</parameter>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
The first parameter, <replaceable>parser</replaceable>, is a
|
|
reference to the XML parser calling the
|
|
handler.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>data</parameter>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
The second parameter, <parameter>data</parameter>, contains
|
|
the character data. This may be the XML declaration,
|
|
document type declaration, entities or other data for which
|
|
no other handler exists.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
If a handler function is set to an empty string, or
|
|
&false;, the handler in question is disabled.
|
|
</para>
|
|
<para>
|
|
&true; is returned if the handler is set up, &false; if
|
|
<parameter>parser</parameter> is not a parser.
|
|
</para>
|
|
¬e.func-callback;
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-set-unparsed-entity-decl-handler">
|
|
<refnamediv>
|
|
<refname>xml_set_unparsed_entity_decl_handler</refname>
|
|
<refpurpose>
|
|
Set up unparsed entity declaration handler
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_set_unparsed_entity_decl_handler</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>handler</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sets the unparsed entity declaration handler function for the XML
|
|
parser <parameter>parser</parameter>.
|
|
<parameter>handler</parameter> is a string containing the name of
|
|
a function that must exist when <function>xml_parse</function> is
|
|
called for <parameter>parser</parameter>.</para>
|
|
<para>
|
|
This handler will be called if the XML parser encounters an
|
|
external entity declaration with an NDATA declaration, like the
|
|
following:
|
|
<programlisting role="xml">
|
|
<!ENTITY <parameter>name</parameter> {<parameter>publicId</parameter> | <parameter>systemId</parameter>}
|
|
NDATA <parameter>notationName</parameter>>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
See <ulink url="&url.rec-xml;#sec-external-ent">section 4.2.2 of
|
|
the XML 1.0 spec</ulink> for the definition of notation declared
|
|
external entities.
|
|
</para>
|
|
<para> The function named by
|
|
<parameter>handler</parameter> must accept six parameters:
|
|
<methodsynopsis>
|
|
<methodname><replaceable>handler</replaceable></methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>entityName</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>base</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>systemId</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>publicId</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>notationName</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The first parameter, <replaceable>parser</replaceable>, is a
|
|
reference to the XML parser calling the
|
|
handler.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>entityName</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The name of the entity that is about to be defined.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>base</parameter></term>
|
|
<listitem><simpara>
|
|
This is the base for resolving the system identifier
|
|
(<parameter>systemId</parameter>) of the external
|
|
entity. Currently this parameter will always be set to
|
|
an empty string.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>systemId</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
System identifier for the external entity.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>publicId</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
Public identifier for the external entity.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>notationName</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
Name of the notation of this entity (see
|
|
<function>xml_set_notation_decl_handler</function>).
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
<para>
|
|
If a handler function is set to an empty string, or
|
|
&false;, the handler in question is disabled.
|
|
</para>
|
|
<para>
|
|
&true; is returned if the handler is set up, &false; if
|
|
<parameter>parser</parameter> is not a parser.
|
|
</para>
|
|
¬e.func-callback;
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-set-notation-decl-handler">
|
|
<refnamediv>
|
|
<refname>xml_set_notation_decl_handler</refname>
|
|
<refpurpose>set up notation declaration handler</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_set_notation_decl_handler</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>handler</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sets the notation declaration handler function for the XML parser
|
|
<parameter>parser</parameter>. <parameter>handler</parameter> is
|
|
a string containing the name of a function that must exist when
|
|
<function>xml_parse</function> is called for
|
|
<parameter>parser</parameter>.
|
|
</para>
|
|
<para>
|
|
A notation declaration is part of the document's DTD and has the
|
|
following format: <programlisting role="xml"><!NOTATION
|
|
<parameter>name</parameter> {<parameter>systemId</parameter> |
|
|
<parameter>publicId</parameter>}></programlisting> See <ulink
|
|
url="&url.rec-xml;#Notations">section 4.7 of the XML 1.0
|
|
spec</ulink> for the definition of notation declarations.
|
|
</para>
|
|
<para>
|
|
The function named by <parameter>handler</parameter> must accept
|
|
five parameters:
|
|
<methodsynopsis>
|
|
<methodname><replaceable>handler</replaceable></methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>notationName</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>base</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>systemId</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>publicId</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>parser</parameter>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
The first parameter, <replaceable>parser</replaceable>, is a
|
|
reference to the XML parser calling the
|
|
handler.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>notationName</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
This is the notation's <parameter>name</parameter>, as per
|
|
the notation format described above.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>base</parameter>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
This is the base for resolving the system identifier
|
|
(<parameter>systemId</parameter>) of the notation
|
|
declaration. Currently this parameter will always be set to
|
|
an empty string.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>systemId</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
System identifier of the external notation
|
|
declaration.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<parameter>publicId</parameter>
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Public identifier of the external notation
|
|
declaration.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
If a handler function is set to an empty string, or
|
|
&false;, the handler in question is
|
|
disabled.
|
|
</para>
|
|
<para>
|
|
&true; is returned if the handler is set up, &false; if
|
|
<parameter>parser</parameter> is not a parser.
|
|
</para>
|
|
¬e.func-callback;
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-set-external-entity-ref-handler">
|
|
<refnamediv>
|
|
<refname>xml_set_external_entity_ref_handler</refname>
|
|
<refpurpose>set up external entity reference handler</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_set_external_entity_ref_handler</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>handler</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sets the notation declaration handler function for the XML parser
|
|
<parameter>parser</parameter>. <parameter>handler</parameter> is
|
|
a string containing the name of a function that must exist when
|
|
<function>xml_parse</function> is called for
|
|
<parameter>parser</parameter>.
|
|
</para>
|
|
<para>
|
|
The function named by <parameter>handler</parameter> must accept
|
|
five parameters, and should return an integer value. If the
|
|
value returned from the handler is &false; (which it will be if no
|
|
value is returned), the XML parser will stop parsing and
|
|
<function>xml_get_error_code</function> will return <systemitem
|
|
class="constant">XML_ERROR_EXTERNAL_ENTITY_HANDLING</systemitem>.
|
|
<methodsynopsis>
|
|
<type>int</type><methodname><replaceable>handler</replaceable></methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>openEntityNames</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>base</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>systemId</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>publicId</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The first parameter, <replaceable>parser</replaceable>, is a
|
|
reference to the XML parser calling the handler.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>openEntityNames</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The second parameter, <parameter>openEntityNames</parameter>,
|
|
is a space-separated list of the names of the entities that
|
|
are open for the parse of this entity (including the name of
|
|
the referenced entity).
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>base</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
This is the base for resolving the system identifier
|
|
(<parameter>systemid</parameter>) of the external entity.
|
|
Currently this parameter will always be set to an empty
|
|
string.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>systemId</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The fourth parameter, <parameter>systemId</parameter>, is the
|
|
system identifier as specified in the entity declaration.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>publicId</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The fifth parameter, <parameter>publicId</parameter>, is the
|
|
public identifier as specified in the entity declaration, or
|
|
an empty string if none was specified; the whitespace in the
|
|
public identifier will have been normalized as required by
|
|
the XML spec.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
If a handler function is set to an empty string, or
|
|
&false;, the handler in question is
|
|
disabled.
|
|
</para>
|
|
<para>
|
|
&true; is returned if the handler is set up, &false; if
|
|
<parameter>parser</parameter> is not a parser.
|
|
</para>
|
|
¬e.func-callback;
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-parse">
|
|
<refnamediv>
|
|
<refname>xml_parse</refname>
|
|
<refpurpose>start parsing an XML document</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_parse</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>data</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>isFinal</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
A reference to the XML parser to use.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>data</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
Chunk of data to parse. A document may be parsed piece-wise
|
|
by calling <function>xml_parse</function> several times with
|
|
new data, as long as the <parameter>isFinal</parameter>
|
|
parameter is set and &true; when the last data is parsed.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>isFinal</parameter> (optional)</term>
|
|
<listitem>
|
|
<simpara>
|
|
If set and &true;, <parameter>data</parameter> is the last
|
|
piece of data sent in this parse.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
When the XML document is parsed, the handlers for the configured
|
|
events are called as many times as necessary, after which this
|
|
function returns &true; or &false;.
|
|
</para>
|
|
<para>
|
|
&true; is returned if the parse was successful, &false; if it was not
|
|
successful, or if <parameter>parser</parameter> does not refer to
|
|
a valid parser. For unsuccessful parses, error information can
|
|
be retrieved with <function>xml_get_error_code</function>,
|
|
<function>xml_error_string</function>,
|
|
<function>xml_get_current_line_number</function>,
|
|
<function>xml_get_current_column_number</function> and
|
|
<function>xml_get_current_byte_index</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-get-error-code">
|
|
<refnamediv>
|
|
<refname>xml_get_error_code</refname>
|
|
<refpurpose>get XML parser error code</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_get_error_code</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
A reference to the XML parser to get error code from.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
This function returns &false; if <parameter>parser</parameter> does
|
|
not refer to a valid parser, or else it returns one of the error
|
|
codes listed in the <link linkend="xml.error-codes">error codes
|
|
section</link>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-error-string">
|
|
<refnamediv>
|
|
<refname>xml_error_string</refname>
|
|
<refpurpose>get XML parser error string</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>xml_error_string</methodname>
|
|
<methodparam><type>int</type><parameter>code</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>code</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
An error code from <function>xml_get_error_code</function>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
Returns a string with a textual description of the error code
|
|
<parameter>code</parameter>, or &false; if no description was found.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-get-current-line-number">
|
|
<refnamediv>
|
|
<refname>xml_get_current_line_number</refname>
|
|
<refpurpose>get current line number for an XML parser</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_get_current_line_number</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
A reference to the XML parser to get line number from.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
This function returns &false; if <parameter>parser</parameter> does
|
|
not refer to a valid parser, or else it returns which line the
|
|
parser is currently at in its data buffer.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-get-current-column-number">
|
|
<refnamediv>
|
|
<refname>xml_get_current_column_number</refname>
|
|
<refpurpose>
|
|
Get current column number for an XML parser
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_get_current_column_number</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
A reference to the XML parser to get column number from.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
This function returns &false; if <parameter>parser</parameter> does
|
|
not refer to a valid parser, or else it returns which column on
|
|
the current line (as given by
|
|
<function>xml_get_current_line_number</function>) the parser is
|
|
currently at.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-get-current-byte-index">
|
|
<refnamediv>
|
|
<refname>xml_get_current_byte_index</refname>
|
|
<refpurpose>get current byte index for an XML parser</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_get_current_byte_index</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
A reference to the XML parser to get byte index from.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
This function returns &false; if <parameter>parser</parameter> does
|
|
not refer to a valid parser, or else it returns which byte index
|
|
the parser is currently at in its data buffer (starting at 0).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-parse-into-struct">
|
|
<refnamediv>
|
|
<refname>xml_parse_into_struct</refname>
|
|
<refpurpose>Parse XML data into an array structure</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_parse_into_struct</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>data</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>&values</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>&index</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function parses an XML file into 2 parallel array
|
|
structures, one (<parameter>index</parameter>) containing pointers
|
|
to the location of the appropriate values in the
|
|
<parameter>values</parameter> array. These last two parameters
|
|
must be passed by reference.
|
|
</para>
|
|
<para>
|
|
Below is an example that illustrates the internal structure of
|
|
the arrays being generated by the function. We use a simple
|
|
<literal>note</literal> tag embeded inside a
|
|
<literal>para</literal> tag, and then we parse this an print out
|
|
the structures generated:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$simple = "<para><note>simple note</note></para>";
|
|
$p = xml_parser_create();
|
|
xml_parse_into_struct($p,$simple,$vals,$index);
|
|
xml_parser_free($p);
|
|
echo "Index array\n";
|
|
print_r($index);
|
|
echo "\nVals array\n";
|
|
print_r($vals);
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
When we run that code, the output will be:
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
Index array
|
|
Array
|
|
(
|
|
[PARA] => Array
|
|
(
|
|
[0] => 0
|
|
[1] => 2
|
|
)
|
|
|
|
[NOTE] => Array
|
|
(
|
|
[0] => 1
|
|
)
|
|
|
|
)
|
|
|
|
Vals array
|
|
Array
|
|
(
|
|
[0] => Array
|
|
(
|
|
[tag] => PARA
|
|
[type] => open
|
|
[level] => 1
|
|
)
|
|
|
|
[1] => Array
|
|
(
|
|
[tag] => NOTE
|
|
[type] => complete
|
|
[level] => 2
|
|
[value] => simple note
|
|
)
|
|
|
|
[2] => Array
|
|
(
|
|
[tag] => PARA
|
|
[type] => close
|
|
[level] => 1
|
|
)
|
|
|
|
)
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Event-driven parsing (based on the expat library) can get
|
|
complicated when you have an XML document that is complex.
|
|
This function does not produce a DOM style object, but it
|
|
generates structures amenable of being transversed in a tree
|
|
fashion. Thus, we can create objects representing the data
|
|
in the XML file easily. Let's consider the following XML file
|
|
representing a small database of aminoacids information:
|
|
<example>
|
|
<title>moldb.xml - small database of molecular information</title>
|
|
<programlisting role="xml">
|
|
<![CDATA[
|
|
<?xml version="1.0"?>
|
|
<moldb>
|
|
|
|
<molecule>
|
|
<name>Alanine</name>
|
|
<symbol>ala</symbol>
|
|
<code>A</code>
|
|
<type>hydrophobic</type>
|
|
</molecule>
|
|
|
|
<molecule>
|
|
<name>Lysine</name>
|
|
<symbol>lys</symbol>
|
|
<code>K</code>
|
|
<type>charged</type>
|
|
</molecule>
|
|
|
|
</moldb>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
And some code to parse the document and generate the appropriate
|
|
objects:
|
|
<example>
|
|
<title>
|
|
parsemoldb.php - parses moldb.xml into and array of
|
|
molecular objects
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
class AminoAcid {
|
|
var $name; // aa name
|
|
var $symbol; // three letter symbol
|
|
var $code; // one letter code
|
|
var $type; // hydrophobic, charged or neutral
|
|
|
|
function AminoAcid ($aa) {
|
|
foreach ($aa as $k=>$v)
|
|
$this->$k = $aa[$k];
|
|
}
|
|
}
|
|
|
|
function readDatabase($filename) {
|
|
// read the xml database of aminoacids
|
|
$data = implode("",file($filename));
|
|
$parser = xml_parser_create();
|
|
xml_parser_set_option($parser,XML_OPTION_CASE_FOLDING,0);
|
|
xml_parser_set_option($parser,XML_OPTION_SKIP_WHITE,1);
|
|
xml_parse_into_struct($parser,$data,$values,$tags);
|
|
xml_parser_free($parser);
|
|
|
|
// loop through the structures
|
|
foreach ($tags as $key=>$val) {
|
|
if ($key == "molecule") {
|
|
$molranges = $val;
|
|
// each contiguous pair of array entries are the
|
|
// lower and upper range for each molecule definition
|
|
for ($i=0; $i < count($molranges); $i+=2) {
|
|
$offset = $molranges[$i] + 1;
|
|
$len = $molranges[$i + 1] - $offset;
|
|
$tdb[] = parseMol(array_slice($values, $offset, $len));
|
|
}
|
|
} else {
|
|
continue;
|
|
}
|
|
}
|
|
return $tdb;
|
|
}
|
|
|
|
function parseMol($mvalues) {
|
|
for ($i=0; $i < count($mvalues); $i++)
|
|
$mol[$mvalues[$i]["tag"]] = $mvalues[$i]["value"];
|
|
return new AminoAcid($mol);
|
|
}
|
|
|
|
$db = readDatabase("moldb.xml");
|
|
echo "** Database of AminoAcid objects:\n";
|
|
print_r($db);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
After executing <filename>parsemoldb.php</filename>, the variable
|
|
<varname>$db</varname> contains an array of
|
|
<classname>AminoAcid</classname> objects, and the output of the
|
|
script confirms that:
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
** Database of AminoAcid objects:
|
|
Array
|
|
(
|
|
[0] => aminoacid Object
|
|
(
|
|
[name] => Alanine
|
|
[symbol] => ala
|
|
[code] => A
|
|
[type] => hydrophobic
|
|
)
|
|
|
|
[1] => aminoacid Object
|
|
(
|
|
[name] => Lysine
|
|
[symbol] => lys
|
|
[code] => K
|
|
[type] => charged
|
|
)
|
|
|
|
)
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-parser-free">
|
|
<refnamediv>
|
|
<refname>xml_parser_free</refname>
|
|
<refpurpose>Free an XML parser</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>xml_parser_free</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
A reference to the XML parser to free.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
<para>
|
|
This function returns &false; if <parameter>parser</parameter> does
|
|
not refer to a valid parser, or else it frees the parser and
|
|
returns &true;.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-parser-set-option">
|
|
<refnamediv>
|
|
<refname>xml_parser_set_option</refname>
|
|
<refpurpose>set options in an XML parser</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_parser_set_option</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>int</type><parameter>option</parameter></methodparam>
|
|
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
A reference to the XML parser to set an option in.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>option</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
Which option to set. See below.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>value</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The option's new value.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
This function returns &false; if <parameter>parser</parameter> does
|
|
not refer to a valid parser, or if the option could not be set.
|
|
Else the option is set and &true; is returned.
|
|
</para>
|
|
<para>
|
|
The following options are available:
|
|
<table>
|
|
<title>XML parser options</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Option constant</entry>
|
|
<entry>Data type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>XML_OPTION_CASE_FOLDING</entry>
|
|
<entry>integer</entry>
|
|
<entry>
|
|
Controls whether <link
|
|
linkend="xml.case-folding">case-folding</link> is enabled
|
|
for this XML parser. Enabled by default.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XML_OPTION_TARGET_ENCODING</entry>
|
|
<entry>string</entry>
|
|
<entry>
|
|
Sets which <link linkend="xml.encoding">target
|
|
encoding</link> to use in this XML parser. By default, it
|
|
is set to the same as the source encoding used by
|
|
<function>xml_parser_create</function>. Supported target
|
|
encodings are <literal>ISO-8859-1</literal>,
|
|
<literal>US-ASCII</literal> and <literal>UTF-8</literal>.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xml-parser-get-option">
|
|
<refnamediv>
|
|
<refname>xml_parser_get_option</refname>
|
|
<refpurpose>get options from an XML parser</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>xml_parser_get_option</methodname>
|
|
<methodparam><type>int</type><parameter>parser</parameter></methodparam>
|
|
<methodparam><type>int</type><parameter>option</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>parser</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
A reference to the XML parser to get an option
|
|
from.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>option</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
Which option to fetch. See
|
|
<function>xml_parser_set_option</function> for a list of
|
|
options.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
This function returns &false; if <parameter>parser</parameter> does
|
|
not refer to a valid parser, or if the option could not be set.
|
|
Else the option's value is returned.
|
|
</para>
|
|
<para>
|
|
See <function>xml_parser_set_option</function> for the list of
|
|
options.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.utf8-decode">
|
|
<refnamediv>
|
|
<refname>utf8_decode</refname>
|
|
<refpurpose>
|
|
Converts a string with ISO-8859-1 characters encoded with UTF-8
|
|
to single-byte ISO-8859-1.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>utf8_decode</methodname>
|
|
<methodparam><type>string</type><parameter>data</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function decodes <parameter>data</parameter>, assumed to be
|
|
<literal>UTF-8</literal> encoded, to <literal>ISO-8859-1</literal>.
|
|
</para>
|
|
<para>
|
|
See <function>utf8_encode</function> for an explaination of UTF-8
|
|
encoding.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.utf8-encode">
|
|
<refnamediv>
|
|
<refname>utf8_encode</refname>
|
|
<refpurpose>encodes an ISO-8859-1 string to UTF-8</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>utf8_encode</methodname>
|
|
<methodparam><type>string</type><parameter>data</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function encodes the string <parameter>data</parameter> to
|
|
<literal>UTF-8</literal>, and returns the encoded version.
|
|
<literal>UTF-8</literal> is a standard mechanism used by
|
|
<acronym>Unicode</acronym>for encoding <glossterm>wide
|
|
character</glossterm> values into a byte stream.
|
|
<literal>UTF-8</literal> is transparent to plain
|
|
<abbrev>ASCII</abbrev> characters, is self-synchronized (meaning
|
|
it is possible for a program to figure out where in the
|
|
bytestream characters start) and can be used with normal string
|
|
comparison functions for sorting and such. PHP encodes
|
|
<literal>UTF-8</literal> characters in up to four bytes, like
|
|
this:
|
|
<table>
|
|
<title>UTF-8 encoding</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>bytes</entry>
|
|
<entry>bits</entry>
|
|
<entry>representation</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>1</entry>
|
|
<entry>7</entry>
|
|
<entry>0bbbbbbb</entry>
|
|
</row>
|
|
<row>
|
|
<entry>2</entry>
|
|
<entry>11</entry>
|
|
<entry>110bbbbb 10bbbbbb</entry>
|
|
</row>
|
|
<row>
|
|
<entry>3</entry>
|
|
<entry>16</entry>
|
|
<entry>1110bbbb 10bbbbbb 10bbbbbb</entry>
|
|
</row>
|
|
<row>
|
|
<entry>4</entry>
|
|
<entry>21</entry>
|
|
<entry>11110bbb 10bbbbbb 10bbbbbb 10bbbbbb</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
Each <replaceable>b</replaceable> represents a bit that can be
|
|
used to store character data.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id='function.xml-parser-create-ns'>
|
|
<refnamediv>
|
|
<refname>xml_parser_create_ns</refname>
|
|
<refpurpose>
|
|
Create an XML parser
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_parser_create_ns</methodname>
|
|
<methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>sep</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
&warn.undocumented.func;
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
|
|
<refentry id='function.xml-set-end-namespace-decl-handler'>
|
|
<refnamediv>
|
|
<refname>xml_set_end_namespace_decl_handler</refname>
|
|
<refpurpose>
|
|
Set up character data handler
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_set_end_namespace_decl_handler</methodname>
|
|
<methodparam><type>int</type><parameter>pind</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>hdl</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
&warn.undocumented.func;
|
|
</para>
|
|
¬e.func-callback;
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
|
|
<refentry id='function.xml-set-start-namespace-decl-handler'>
|
|
<refnamediv>
|
|
<refname>xml_set_start_namespace_decl_handler</refname>
|
|
<refpurpose>
|
|
Set up character data handler
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>xml_set_start_namespace_decl_handler</methodname>
|
|
<methodparam><type>int</type><parameter>pind</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>hdl</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
&warn.undocumented.func;
|
|
</para>
|
|
¬e.func-callback;
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
</reference>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|
|
|