<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.18 $ -->
<!-- splitted from ./en/functions/xslt.xml, last change in rev 1.3 -->
  <refentry id="function.xslt-process">
   <refnamediv>
    <refname>xslt_process</refname>
    <refpurpose>Perform an XSLT transformation</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <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 new
     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. 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>
    <para>
     <warning>
      <simpara>
       As of PHP 4.0.6, 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.
      </simpara>
     </warning>
    </para>
    <para>
     Containers can also be set via the <parameter>arguments</parameter>
  array (see below).
    </para>
    <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 &quot;argument&quot; syntax, comes to the 
     rescue.  Instead of files as the XML and XSLT arguments to the <function>xslt_process</function>
     function, you can specify &quot;argument place holders&quot; 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>
     Finally, the last argument to the <function>xslt_process</function>
     function represents an array for any top-level parameters that you want to
     pass to the XSLT document.  These parameters can then be accessed within
     your XSL files using the &lt;xsl:param name=&quot;parameter_name&quot;&gt;
     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>
    <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 : &lt;foo&gt;bar&lt;/foo&gt;
]]>
      </screen>
     </example>
    </para>
    &note.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
-->