<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<refentry xml:id="function.xslt-process" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>xslt_process</refname>
  <refpurpose>Perform an <acronym>XSLT</acronym> 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 <acronym>XSLT</acronym>
   extension.  It allows you to perform an <acronym>XSLT</acronym> transformation using
   almost any type of input source - the containers.  This is accomplished
   through the use of argument buffers -- a concept taken from the <productname>Sablotron</productname>
   <acronym>XSLT</acronym> processor (currently the only <acronym>XSLT</acronym> 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 <acronym>XSLT</acronym> processor link identifier, created with
       <function>xslt_create</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>xmlcontainer</parameter></term>
     <listitem>
      <para>
       Path to <acronym>XML</acronym> file or placeholder for the
       <acronym>XML</acronym> argument.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>xslcontainer</parameter></term>
     <listitem>
      <para>
       Path to <acronym>XSL</acronym> file or placeholder for the
       <acronym>XML</acronym> 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 <acronym>XML</acronym> and <acronym>XSLT</acronym> 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 <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 <literal>&lt;xsl:param name=&quot;parameter_name&quot;&gt;</literal>
       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 <literal>node-sets</literal> as parameters to
       the <acronym>XSLT</acronym> 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
   <acronym>XML</acronym> file with an <acronym>XSLT</acronym> file, placing the result
   in a third file containing the new <acronym>XML</acronym> (or HTML) document.  Doing
   this with <productname>Sablotron</productname> is really quite easy...
  </para>
  <example>
   <title>Using the <function>xslt_process</function> to transform an <acronym>XML</acronym>
   file and a <acronym>XSL</acronym> file to a new <acronym>XML</acronym> 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 <acronym>XSLT</acronym> transformation, instead of writing it to a
   file...
  </para>
  <para>
   <example>
   <title>Using the <function>xslt_process</function> to transform an <acronym>XML</acronym> file
   and a <acronym>XSL</acronym> 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 <acronym>XML</acronym> and
   <acronym>XSLT</acronym> code from external sources, such as a database or a socket.  In these cases you'll have
   the <acronym>XML</acronym> and/or <acronym>XSLT</acronym> data in a variable -- and in production applications the overhead of dumping
   these to file may be too much.  This is where <acronym>XSLT</acronym>'s &quot;argument&quot; syntax, comes to the
   rescue.  Instead of files as the <acronym>XML</acronym> and <acronym>XSLT</acronym> 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 <acronym>XML</acronym> and <acronym>XSLT</acronym> 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 <acronym>XML</acronym> data
   and a variable containing <acronym>XSL</acronym> data into a variable containing the resulting <acronym>XML</acronym> 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 : &lt;foo&gt;bar&lt;/foo&gt;
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  &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:"~/.phpdoc/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
-->