<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.32 $ -->
 <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>
     <methodsynopsis>
      <type>void</type><methodname>xslt_set_log</methodname>
      <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>log</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>resource</type><methodname>xslt_create</methodname>
      <void/>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>xslt_errno</methodname>
       <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>mixed</type><methodname>xslt_error</methodname>
       <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>void</type><methodname>xslt_free</methodname>
       <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>mixed</type><methodname>xslt_process</methodname>
       <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
       <methodparam><type>string</type><parameter>xml</parameter></methodparam>
       <methodparam><type>string</type><parameter>xsl</parameter></methodparam>
       <methodparam choice="opt"><type>string</type><parameter>result</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 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.  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).
    </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')) {
    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 &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 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 &lt;xsl:param name=&quot;parameter_name&quot;&gt; 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>
     <methodsynopsis>
      <type>void</type><methodname>xslt_set_sax_handler</methodname>
       <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
       <methodparam><type>array</type><parameter>handlers</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>void</type><methodname>xslt_set_scheme_handler</methodname>
       <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
       <methodparam><type>array</type><parameter>handlers</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>void</type><methodname>xslt_set_error_handler</methodname>
       <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
       <methodparam><type>mixed</type><parameter>handler</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>void</type><methodname>xslt_set_base</methodname>
       <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
       <methodparam><type>string</type><parameter>uri</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>void</type><methodname>xslt_set_encoding</methodname>
       <methodparam><type>resource</type><parameter>xh</parameter></methodparam>
       <methodparam><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    <para>
     Set the output 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>
     <methodsynopsis>
      <type>void</type><methodname>xslt_set_sax_handlers</methodname>
      <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
      <methodparam><type>array</type><parameter>handlers</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>void</type><methodname>xslt_set_scheme_handlers</methodname>
      <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
      <methodparam><type>array</type><parameter>handlers</parameter></methodparam>
     </methodsynopsis>
    <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
-->