mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-23 04:18:56 +00:00
c030e2adf7
- All id attributes are now xml:id - Add docbook namespace to all root elements - Replace <ulink /> with <link xlink:href /> - Minor markup fixes here and there git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@238160 c90b9560-bf6c-de11-be94-00142212c4b1
344 lines
10 KiB
XML
344 lines
10 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.21 $ -->
|
|
<refentry xml:id="function.xslt-process" xmlns="http://docbook.org/ns/docbook">
|
|
<refnamediv>
|
|
<refname>xslt_process</refname>
|
|
<refpurpose>Perform an XSLT transformation</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>xslt_process</methodname>
|
|
<methodparam><type>resource</type><parameter>xh</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>xmlcontainer</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>xslcontainer</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>resultcontainer</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>arguments</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>parameters</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
The <function>xslt_process</function> function is the crux of the XSLT
|
|
extension. It allows you to perform an XSLT transformation using
|
|
almost any type of input source - the containers. This is accomplished
|
|
through the use of argument buffers -- a concept taken from the Sablotron
|
|
XSLT processor (currently the only XSLT processor this extension supports).
|
|
The input containers default to a filename 'containing' the document to be
|
|
processed.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>xh</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The XSLT processor link identifier, created with
|
|
<function>xslt_create</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>xmlcontainer</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Path to XML file or placeholder for the XML argument.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>xslcontainer</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Path to XSL file or placeholder for the XML argument.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>resultcontainer</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The result container defaults to a filename for the transformed
|
|
document. If the result container is not specified - i.e. &null;
|
|
- than the result is returned.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>arguments</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
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 substituted by values
|
|
given in the <parameter>arguments</parameter> array.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>parameters</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
An array for any top-level parameters that will be passed to the XSLT
|
|
document. These parameters can then be accessed within your XSL files
|
|
using the <xsl:param name="parameter_name">
|
|
instruction. The parameters must be UTF-8 encoded and their values will be
|
|
interpreted as strings by the <productname>Sablotron</productname> processor.
|
|
In other words - you cannot pass node-sets as parameters to the XSLT document.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
Containers can also be set via the <parameter>arguments</parameter>
|
|
array (see below).
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
&return.success; If the result container is not specified - i.e.
|
|
&null; - than the result is returned.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>4.0.6</entry>
|
|
<entry>
|
|
This function no longer takes XML strings in
|
|
<parameter>xmlcontainer</parameter> or
|
|
<parameter>xslcontainer</parameter>. Passing a string containing XML
|
|
to either of these parameters will result in a segmentation fault in
|
|
Sablotron versions up to and including version 0.95.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
The simplest type of transformation with the
|
|
<function>xslt_process</function> function is the transformation of an
|
|
XML file with an XSLT file, placing the result in a third file containing
|
|
the new XML (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')) {
|
|
echo "SUCCESS, sample.xml was transformed by sample.xsl into result.xml";
|
|
echo ", result.xml has the following contents\n<br />\n";
|
|
echo "<pre>\n";
|
|
readfile('result.xml');
|
|
echo "</pre>\n";
|
|
} else {
|
|
echo "Sorry, sample.xml could not be transformed by sample.xsl into";
|
|
echo " result.xml the reason is that " . xslt_error($xh) . " and the ";
|
|
echo "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) {
|
|
echo "SUCCESS, sample.xml was transformed by sample.xsl into the \$result";
|
|
echo " variable, the \$result variable has the following contents\n<br />\n";
|
|
echo "<pre>\n";
|
|
echo $result;
|
|
echo "</pre>\n";
|
|
} else {
|
|
echo "Sorry, sample.xml could not be transformed by sample.xsl into";
|
|
echo " the \$result variable the reason is that " . xslt_error($xh);
|
|
echo " 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 substituted 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) {
|
|
echo "SUCCESS, sample.xml was transformed by sample.xsl into the \$result";
|
|
echo " variable, the \$result variable has the following contents\n<br />\n";
|
|
echo "<pre>\n";
|
|
echo $result;
|
|
echo "</pre>\n";
|
|
} else {
|
|
echo "Sorry, sample.xml could not be transformed by sample.xsl into";
|
|
echo " the \$result variable the reason is that " . xslt_error($xh);
|
|
echo " and the error code is " . xslt_errno($xh);
|
|
}
|
|
xslt_free($xh);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Passing PHP variables to XSL files</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
// XML string
|
|
$xml = '<?xml version="1.0"?>
|
|
<para>
|
|
change me
|
|
</para>';
|
|
|
|
// XSL string
|
|
$xsl = '
|
|
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
|
<xsl:output method="html" encoding="ISO-8859-1" indent="no"
|
|
omit-xml-declaration="yes" media-type="text/html"/>
|
|
<xsl:param name="myvar"/>
|
|
<xsl:param name="mynode"/>
|
|
<xsl:template match="/">
|
|
My PHP variable : <xsl:value-of select="$myvar"/><br />
|
|
My node set : <xsl:value-of select="$mynode"/>
|
|
</xsl:template>
|
|
</xsl:stylesheet>';
|
|
|
|
|
|
$xh = xslt_create();
|
|
|
|
// the second parameter will be interpreted as a string
|
|
$parameters = array (
|
|
'myvar' => 'test',
|
|
'mynode' => '<foo>bar</foo>'
|
|
);
|
|
|
|
$arguments = array (
|
|
'/_xml' => $xml,
|
|
'/_xsl' => $xsl
|
|
);
|
|
|
|
echo xslt_process($xh, 'arg:/_xml', 'arg:/_xsl', NULL, $arguments, $parameters);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
My PHP variable : test<br>
|
|
My node set : <foo>bar</foo>
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
¬e.xslt.windows;
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- 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
|
|
-->
|