diff --git a/functions/xslt.xml b/functions/xslt.xml index cae231f248..b18d11de31 100644 --- a/functions/xslt.xml +++ b/functions/xslt.xml @@ -1,11 +1,10 @@ - + XSLT functions XSLT - &warn.experimental; Introduction @@ -24,7 +23,7 @@ Installation - This extension uses Sabloton + This extension uses Sablotron and expat, which can both be found at &url.sablotron;. Binaries @@ -32,8 +31,8 @@ On UNIX, run configure with the . - The Sablotron library + role="configure">--enable-xslt --with-xslt-sablot + options. The Sablotron library should be installed somewhere your compiler can find it. @@ -41,33 +40,38 @@ About This Extension - This PHP extension implements support - Sablotron from Ginger Alliance - in PHP. This toolkit lets you transform - XML documents into other documents, including new XML - documents, but also into HTML or other target formats. It - basically provides a standardized and portable template - mechanism, separating content and design of a website. + 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. + + + 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. + + - + - xslt_closelog - Clear the logfile for a given instance of Sablotron + xslt_set_log + Set the log file to write log messages to Description - bool xslt_closelog + void xslt_set_log resource xh + mixed log - &warn.experimental.func; @@ -78,11 +82,47 @@ + + log + + + This parameter is either a boolean value which toggles logging on and off, or a + string containing the logfile in which log errors too. + + + - This function returns &false; if parser does - not refer to a valid parser, or if the closing of the logfile - fails. Otherwise it returns &true;. + 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. + + + By default logging is disabled, in order to enable logging you must first call + xslt_set_log 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: + + + Using the XSLT Logging features + + + +]]> + + @@ -90,7 +130,7 @@ xslt_create - Create a new XSL processor. + Create a new XSLT processor. Description @@ -100,10 +140,9 @@ - &warn.experimental.func; - This function returns a handle for a new XSL processor. This handle - is needed in all subsequent calls to XSL functions. + Create and return a new XSLT processor resource for manipulation by the + other XSLT functions. @@ -111,7 +150,7 @@ xslt_errno - Return the current error number + Return a error number Description @@ -123,11 +162,9 @@ - &warn.experimental.func; - Return the current error number of the given XSL processor. If - no handle is given, the last error number that occured anywhere - is returned. + Return an error code describing the last error that occured on the + passed XSLT processor. @@ -135,7 +172,7 @@ xslt_error - Return the current error string + Return a error string Description @@ -147,34 +184,34 @@ - &warn.experimental.func; - Return the current error string of the given XSL processor. If - no handle is given, the last error string that occured anywhere - is returned. + Return a string describing the last error that occured on the + passed XSLT processor. - - - - - - xslt_fetch_result - Fetch a (named) result buffer - - - Description - - - string xslt_fetch_result - resource xh - string result_name - - - &warn.experimental.func; - Fetch a result buffer from the XSLT processor identified by - the given handle. If no result name is given, the - buffer named "/_result" is fetched. + + + Handling errors using the <function>xslt_error</function> and + <function>xslt_errno</function> functions. + + + +]]> + + @@ -194,235 +231,168 @@ - &warn.experimental.func; Free the XSLT processor identified by the given handle. - - - xslt_openlog - Set a logfile for XSLT processor messages - - - Description - - - bool xslt_openlog - resource xh - string logfile - int loglevel - - - &warn.experimental.func; - - Set a logfile for the XSLT processor to place all of its error - messages. - - - - - - - xslt_output_begintransform - Begin an XSLT transformation on the output - - - Description - - - void - xslt_output_begintransform - - - string xslt_filename - - - - &warn.experimental.func; - - This function will begin the output transformation on your data. - From the point you call xslt_output_begintransform - till the point you call xslt_output_endtransform - all output will be transformed through the xslt stylesheet given by - the first argument. - - - - - This function does not currently support nested output transformations. - - - - - - - Transforming output through an XSLT stylesheet, using the DOM-XML functions for xml generation - - -new_root('article'); - -$article->new_child('title', 'The History of South Tyrol'); -$article->new_child('author', 'Sterling Hughes'); -$article->new_child('body', 'Back after WWI, Italy gained South Tyrol from - Austria. Since that point nothing interesting has - happened'); - -echo $doc->dumpmem(); - -xslt_output_endtransform(); -]]> - - - - - - - - - xslt_output_endtransform - End an output transformation started with xslt_output_begintransform - - - Description - - - void - xslt_output_endtransform - - - - - &warn.experimental.func; - - The xslt_output_endtransform ends the output transformation - started by the xslt_output_begintransform function. You must call - this function in order to see the results of the output transformation. - - - - xslt_process - Transform XML data through a string containing XSL data + Perform an XSLT transformation Description - bool + mixed xslt_process - string xsl_data - string xml_data - string result + resource xh + string xml + string xsl + string result + array arguments + array parameters - &warn.experimental.func; - The xslt_process takes a string containing the XSLT stylesheet as - its first argument, it takes a second string containing the XML data you want to - transform and then a third string containing the results of the transformation. - xslt_process will return &true; on success and &false; on failure, - to get the error number and error string if an error occurs use the - xslt_errno and xslt_error functions. + 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). + + The simplest type of transformation with the xslt_process 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... - Using the <function>xslt_process</function> to transform three strings + Using the <function>xslt_process</function> to transform an XML file and a XSL file + to a new XML file +// Allocate a new XSLT processor +$xh = xslt_create(); - - - - - - -
- &#160; - -

-

-
- - -
- - -'; - -$xmlData = ' -
- Learning German - Sterling Hughes -

- Essential phrases: -
- K#246;nnen Sie mir sagen, wo die Toilette ist?
- Ein grosses Bier, bitte!
- Noch eins, bitte.
-

-
'; - -if (xslt_process($xslData, $xmlData, $result)) { - echo "Here is the brilliant in-depth article on learning"; - echo " German: "; - echo "
\n
"; - echo $result; -} else { - echo "There was an error that occurred in the XSL transformation...\n"; - echo "\tError number: " . xslt_errno() . "\n"; - echo "\tError string: " . xslt_error() . "\n"; - exit; +// 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
\n"; + print "
\n";
+    readfile('result.xml');
+    print "
\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); + ?> ]]> - - - - - - xslt_run - Apply a XSLT stylesheet to a file. - - - Description - - - bool xslt_run - resource xh - string xslt_file - string xml_data_file - string result - array xslt_params - array xslt_args - - - &warn.experimental.func; - Process the xml_data_file by applying the xslt_file stylesheet to - it. The stylesheet has access to xslt_params and the processor - is started with xslt_args. The result of the XSLT transformation - is placed in the named buffer (default is "/_result"). + 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 xslt_process 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... + + + + Using the <function>xslt_process</function> to transform an XML file and a XSL file + to a variable containing the resulting XML data + +\n"; + print "
\n";
+    print $result;
+    print "
\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); + +?> +]]> + + + + + 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 xslt_process + function, you can specify "argument place holders" which are then subsituted by values + given in the arguments array (5th parameter to the xslt_process function). + The following is an example of processing XML and XSLT into a result variable without the use + of files at all. + + + + 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 + + $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
\n"; + print "
\n";
+    print $result;
+    print "
\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); +?> +]]> + + + + + Finally, the last argument to the xslt_process 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. @@ -436,43 +406,141 @@ if (xslt_process($xslData, $xmlData, $result)) { Description - bool xslt_set_sax_handler + void xslt_set_sax_handler resource xh array handlers - &warn.experimental.func; Set SAX handlers on the resource handle given by - xh. + xh. SAX handlers should be a two dimensional array + with the format (all top level elements are optional): + + + + 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 +) +]]> + + - + - xslt_transform - Perform an XSLT transformation + xslt_set_scheme_handler + Set Scheme handlers for a XSLT processor Description - bool - xslt_transform - - string xsl - string xml - string result - string params - string args - string resultBuffer + void xslt_set_scheme_handler + resource xh + array handlers - &warn.experimental.func; - The xslt_transform provides an interface to sablotron's - more advanced features without requiring you to use the resource API. + Set Scheme handlers on the resource handle given by + xh. Scheme handlers should be an array with the + format (all elements are optional): + + + get all handler, +[open] => open handler, +[get] => get handler, +[put] => put handler, +[close] => close handler +) +]]> + + + + + + + + + xslt_set_error_handler + Set an error handler for a XSLT processor + + + Description + + + void xslt_set_error_handler + resource xh + mixed handler + + + + Set an error handler function for the XSLT processor given by xh, + this function will be called whenever an error occurs in the XSLT transformation + (this function is also called for notices). + + + + + + + xslt_set_base + Set the base URI for all XSLT transformations + + + Description + + + void xslt_set_base + resource xh + string uri + + + + 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. + + + + + + + xslt_set_encoding + Set the encoding for the parsing of XML documents + + + Description + + + void xslt_set_encoding + resource xh + string encoding + + + + Set the encoding for the XSLT transformations. When using the Sablotron backend this option + is only available when you compile Sablotron with encoding support.