mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-23 20:38:56 +00:00
0fb86ee5f5
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@65492 c90b9560-bf6c-de11-be94-00142212c4b1
615 lines
19 KiB
XML
615 lines
19 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.29 $ -->
|
|
<reference id="ref.xslt">
|
|
<title>XSLT functions</title>
|
|
<titleabbrev>XSLT</titleabbrev>
|
|
|
|
<partintro>
|
|
<sect1 id="xslt.partintro">
|
|
<title>Introduction</title>
|
|
|
|
<sect2 id="xslt.intro">
|
|
<title>About XSLT and Sablotron</title>
|
|
<para>
|
|
XSLT (Extensible Stylesheet Language (XSL)
|
|
Transformations) is a language for transforming XML
|
|
documents into other XML documents. It is a standard
|
|
defined by The World Wide Web consortium (W3C).
|
|
Information about XSLT and related technologies can be
|
|
found at <ulink url="&url.xslt;">&url.xslt;</ulink>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="xslt.install">
|
|
<title>Installation</title>
|
|
<para>
|
|
This extension uses <productname>Sablotron</productname>
|
|
and <productname>expat</productname>, which can both be
|
|
found at <ulink
|
|
url="&url.sablotron;">&url.sablotron;</ulink>. Binaries
|
|
are provided as well as source.
|
|
</para>
|
|
<para>
|
|
On UNIX, run <command>configure</command> with the <option
|
|
role="configure">--enable-xslt --with-xslt-sablot</option>
|
|
options. The <productname>Sablotron</productname> library
|
|
should be installed somewhere your compiler can find it.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="xslt.about">
|
|
<title>About This Extension</title>
|
|
<para>
|
|
This PHP extension provides a processor independent API to XSLT
|
|
transformations. Currently this extension only supports the Sablotron
|
|
library from the Ginger Alliance. Support is planned for other
|
|
libraries, such as the Xalan library or the libxslt library.
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
This extension is different than the sablotron extension distributed with
|
|
versions of PHP prior to PHP 4.1, currently only the new XSLT extension in
|
|
PHP 4.1 is supported. If you need support for the old extension, please ask
|
|
your questions on the php-general@lists.php.net mailing list.
|
|
</simpara>
|
|
</note>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
</partintro>
|
|
|
|
<refentry id="function.xslt-set-log">
|
|
<refnamediv>
|
|
<refname>xslt_set_log</refname>
|
|
<refpurpose>Set the log file to write log messages to</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>xslt_set_log</function></funcdef>
|
|
<paramdef>resource <parameter>xh</parameter></paramdef>
|
|
<paramdef>mixed <parameter>log</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>xh</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
A reference to the XSLT parser.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>log</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
This parameter is either a boolean value which toggles logging on and off, or a
|
|
string containing the logfile in which log errors too.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
<para>
|
|
This function allows you to set the file in which you want XSLT log messages to,
|
|
XSLT log messages are different than error messages, in that log messages are not
|
|
actually error messages but rather messages related to the state of the XSLT processor.
|
|
They are useful for debugging XSLT, when something goes wrong.
|
|
</para>
|
|
<para>
|
|
By default logging is disabled, in order to enable logging you must first call
|
|
<function>xslt_set_log</function> with a boolean parameter which enables logging, then if
|
|
you want to set the log file to debug to, you must then pass it a string containing the
|
|
filename:
|
|
<example>
|
|
<title>
|
|
Using the XSLT Logging features
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$xh = xslt_create();
|
|
xslt_set_log($xh, true);
|
|
xslt_set_log($xh, getcwd() . 'myfile.log');
|
|
|
|
$result = xslt_process($xh, 'dog.xml', 'pets.xsl');
|
|
print($result);
|
|
|
|
xslt_free($xh);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-create">
|
|
<refnamediv>
|
|
<refname>xslt_create</refname>
|
|
<refpurpose>Create a new XSLT processor.</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>xslt_create</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Create and return a new XSLT processor resource for manipulation by the
|
|
other XSLT functions.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-errno">
|
|
<refnamediv>
|
|
<refname>xslt_errno</refname>
|
|
<refpurpose>Return a error number</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>xslt_errno</function></funcdef>
|
|
<paramdef>
|
|
resource <parameter>xh</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Return an error code describing the last error that occured on the
|
|
passed XSLT processor.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-error">
|
|
<refnamediv>
|
|
<refname>xslt_error</refname>
|
|
<refpurpose>Return a error string</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>mixed <function>xslt_error</function></funcdef>
|
|
<paramdef>
|
|
resource <parameter>xh</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Return a string describing the last error that occured on the
|
|
passed XSLT processor.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>
|
|
Handling errors using the <function>xslt_error</function> and
|
|
<function>xslt_errno</function> functions.
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$xh = xslt_create();
|
|
$result = xslt_process($xh, 'dog.xml', 'pets.xsl');
|
|
if (!$result) {
|
|
die(sprintf("Cannot process XSLT document [%d]: %s",
|
|
xslt_errno($xh), xslt_error($xh)));
|
|
}
|
|
|
|
print($result);
|
|
|
|
xslt_free($xh);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-free">
|
|
<refnamediv>
|
|
<refname>xslt_free</refname>
|
|
<refpurpose>Free XSLT processor</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>xslt_free</function></funcdef>
|
|
<paramdef>
|
|
resource <parameter>xh</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Free the XSLT processor identified by the given handle.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-process">
|
|
<refnamediv>
|
|
<refname>xslt_process</refname>
|
|
<refpurpose>Perform an XSLT transformation</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>mixed
|
|
<function>xslt_process</function>
|
|
</funcdef>
|
|
<paramdef>resource <parameter>xh</parameter></paramdef>
|
|
<paramdef>string <parameter>xml</parameter></paramdef>
|
|
<paramdef>string <parameter>xsl</parameter></paramdef>
|
|
<paramdef>string <parameter><optional>result</optional></parameter></paramdef>
|
|
<paramdef>array <parameter><optional>arguments</optional></parameter></paramdef>
|
|
<paramdef>array <parameter><optional>parameters</optional></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The XSLT process function is the crux of the new XSLT extension, it allows you to
|
|
perform an XSLT transformation using almost any type of input source visa-vi the concept
|
|
of argument buffers. Argument buffers is a concept taken from the Sablotron XSLT
|
|
processors (which is currently the only XSLT processor this extension supports).
|
|
</para>
|
|
<para>
|
|
The simplest type of transformation with the <function>xslt_process</function> function
|
|
is transforming an XML file with an XSLT file and placing the result in third file, which
|
|
contains the new XML document (or HTML document). Doing this with sablotron is really quite
|
|
easy...
|
|
</para>
|
|
<example>
|
|
<title>Using the <function>xslt_process</function> to transform an XML file and a XSL file
|
|
to a new XML file</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
// Allocate a new XSLT processor
|
|
$xh = xslt_create();
|
|
|
|
// Process the document
|
|
if (xslt_process($xh, 'sample.xml', 'sample.xsl', 'result.xml')) {
|
|
print "SUCCESS, sample.xml was transformed by sample.xsl into result.xml";
|
|
print ", result.xml has the following contents\n<br>\n";
|
|
print "<pre>\n";
|
|
readfile('result.xml');
|
|
print "</pre>\n";
|
|
}
|
|
else {
|
|
print "Sorry, sample.xml could not be transformed by sample.xsl into";
|
|
print " result.xml the reason is that " . xslt_error($xh) . " and the ";
|
|
print "error code is " . xslt_errno($xh);
|
|
}
|
|
|
|
xslt_free($xh);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
While this functionality is great, many times, especially in a web environment, you want to
|
|
be able to print out your results directly. Therefore, if you omit the third argument to
|
|
the <function>xslt_process</function> function (or provide a NULL value for the argument), it
|
|
will automatically return the value of the XSLT transformation, instead of writing it to a
|
|
file...
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Using the <function>xslt_process</function> to transform an XML file and a XSL file
|
|
to a variable containing the resulting XML data</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
// Allocate a new XSLT processor
|
|
$xh = xslt_create();
|
|
|
|
// Process the document, returning the result into the $result variable
|
|
$result = xslt_process($xh, 'sample.xml', 'sample.xsl');
|
|
if ($result) {
|
|
print "SUCCESS, sample.xml was transformed by sample.xsl into the \$result";
|
|
print " variable, the \$result variable has the following contents\n<br>\n";
|
|
print "<pre>\n";
|
|
print $result;
|
|
print "</pre>\n";
|
|
}
|
|
else {
|
|
print "Sorry, sample.xml could not be transformed by sample.xsl into";
|
|
print " the \$result variable the reason is that " . xslt_error($xh) .
|
|
print " and the error code is " . xslt_errno($xh);
|
|
}
|
|
|
|
xslt_free($xh);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The above two cases are the two simplest cases there are when it comes to XSLT transformation
|
|
and I'd dare say that they are the most common cases, however, sometimes you get your XML and
|
|
XSLT code from external sources, such as a database or a socket. In these cases you'll have
|
|
the XML and/or XSLT data in a variable -- and in production applications the overhead of dumping
|
|
these to file may be too much. This is where XSLT's "argument" syntax, comes to the
|
|
rescue. Instead of files as the XML and XSLT arguments to the <function>xslt_process</function>
|
|
function, you can specify "argument place holders" which are then subsituted by values
|
|
given in the arguments array (5th parameter to the <function>xslt_process</function> function).
|
|
The following is an example of processing XML and XSLT into a result variable without the use
|
|
of files at all.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Using the <function>xslt_process</function> to transform a variable containing XML data
|
|
and a variable containing XSL data into a variable containing the resulting XML data</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// $xml and $xsl contain the XML and XSL data
|
|
|
|
$arguments = array(
|
|
'/_xml' => $xml,
|
|
'/_xsl' => $xsl
|
|
);
|
|
|
|
// Allocate a new XSLT processor
|
|
$xh = xslt_create();
|
|
|
|
// Process the document
|
|
$result = xslt_process($xh, 'arg:/_xml', 'arg:/_xsl', NULL, $arguments);
|
|
if ($result) {
|
|
print "SUCCESS, sample.xml was transformed by sample.xsl into the \$result";
|
|
print " variable, the \$result variable has the following contents\n<br>\n";
|
|
print "<pre>\n";
|
|
print $result;
|
|
print "</pre>\n";
|
|
}
|
|
else {
|
|
print "Sorry, sample.xml could not be transformed by sample.xsl into";
|
|
print " the \$result variable the reason is that " . xslt_error($xh) .
|
|
print " and the error code is " . xslt_errno($xh);
|
|
}
|
|
xslt_free($xh);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
Finally, the last argument to the <function>xslt_process</function> function is any parameters
|
|
that you want to pass to the XSLT document. These parameters can then be accessed within
|
|
your XSL files using the <xsl:param name="parameter_name"> instruction.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-set-sax-handler">
|
|
<refnamediv>
|
|
<refname>xslt_set_sax_handler</refname>
|
|
<refpurpose>Set SAX handlers for a XSLT processor</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>xslt_set_sax_handler</function></funcdef>
|
|
<paramdef>resource <parameter>xh</parameter></paramdef>
|
|
<paramdef>array <parameter>handlers</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Set SAX handlers on the resource handle given by
|
|
<parameter>xh</parameter>. SAX handlers should be a two dimensional array
|
|
with the format (all top level elements are optional):
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
array(
|
|
[document] =>
|
|
array(
|
|
start document handler,
|
|
end document handler
|
|
),
|
|
[element] =>
|
|
array(
|
|
start element handler,
|
|
end element handler
|
|
),
|
|
[namespace] =>
|
|
array(
|
|
start namespace handler,
|
|
end namespace handler
|
|
),
|
|
[comment] => comment handler,
|
|
[pi] => processing instruction handler,
|
|
[character] => character data handler
|
|
)
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-set-scheme-handler">
|
|
<refnamediv>
|
|
<refname>xslt_set_scheme_handler</refname>
|
|
<refpurpose>Set Scheme handlers for a XSLT processor</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>xslt_set_scheme_handler</function></funcdef>
|
|
<paramdef>resource <parameter>xh</parameter></paramdef>
|
|
<paramdef>array <parameter>handlers</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Set Scheme handlers on the resource handle given by
|
|
<parameter>xh</parameter>. Scheme handlers should be an array with the
|
|
format (all elements are optional):
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
array(
|
|
[get_all] => get all handler,
|
|
[open] => open handler,
|
|
[get] => get handler,
|
|
[put] => put handler,
|
|
[close] => close handler
|
|
)
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-set-error-handler">
|
|
<refnamediv>
|
|
<refname>xslt_set_error_handler</refname>
|
|
<refpurpose>Set an error handler for a XSLT processor</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>xslt_set_error_handler</function></funcdef>
|
|
<paramdef>resource <parameter>xh</parameter></paramdef>
|
|
<paramdef>mixed <parameter>handler</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Set an error handler function for the XSLT processor given by <parameter>xh</parameter>,
|
|
this function will be called whenever an error occurs in the XSLT transformation
|
|
(this function is also called for notices).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-set-base">
|
|
<refnamediv>
|
|
<refname>xslt_set_base</refname>
|
|
<refpurpose>Set the base URI for all XSLT transformations</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>xslt_set_base</function></funcdef>
|
|
<paramdef>resource <parameter>xh</parameter></paramdef>
|
|
<paramdef>string <parameter>uri</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Sets the base URI for all XSLT transformations, the base URI is used
|
|
with Xpath instructions to resolve document() and other commands which
|
|
access external resources.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.xslt-set-encoding">
|
|
<refnamediv>
|
|
<refname>xslt_set_encoding</refname>
|
|
<refpurpose>Set the encoding for the parsing of XML documents</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>xslt_set_encoding</function></funcdef>
|
|
<paramdef>resource <parameter>xh</parameter></paramdef>
|
|
<paramdef>string <parameter>encoding</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Set the encoding for the XSLT transformations. When using the Sablotron backend this option
|
|
is only available when you compile Sablotron with encoding support.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id='function.xslt-set-sax-handlers'>
|
|
<refnamediv>
|
|
<refname>xslt_set_sax_handlers</refname>
|
|
<refpurpose>
|
|
Set the SAX handlers to be called when the XML document gets processed
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>xslt_set_sax_handlers</function></funcdef>
|
|
<paramdef>resource <parameter>processor</parameter></paramdef>
|
|
<paramdef>array <parameter>handlers</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
&warn.undocumented.func;
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
|
|
<refentry id='function.xslt-set-scheme-handlers'>
|
|
<refnamediv>
|
|
<refname>xslt_set_scheme_handlers</refname>
|
|
<refpurpose>
|
|
Set the scheme handlers for the XSLT processor
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>xslt_set_scheme_handlers</function></funcdef>
|
|
<paramdef>resource <parameter>processor</parameter></paramdef>
|
|
<paramdef>array <parameter>handlers</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
&warn.undocumented.func;
|
|
</para>
|
|
</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
|
|
-->
|