XSLT (XSL Transformations) plays a vital role in the transformation and presentation of XML documents. Though the primary intent of XSLT was in fact to perform complex styling operations, it has expanded past those boundaries into a general purpose XML process transformation language, providing a mechanism for creating HTML Web pages from XML files.
In order to see the power that XSLT has in your PHP applications, I feel it is best to demonstrate this ability by way of examples. For these examples, I will be using the 4.3.3 version of PHP. The first two examples will focus on the DOM XSLT and the last two will focus on the Sablotron XSLT extension. Please remember that these extensions need to be compiled into PHP before you can run these examples.
There are two sample files that I will be using for all the examples. There is a simple XML file, shown in Listing A, and called example.xml in my sample code. Then there’s a simple XSLT file, shown in Listing B and called example.xslt in my sample code. The examples assume you have these two files stored in the same directory as the example itself.
My first example (Listing C) is a demonstration of the four basic functions that need to take place for an XSLT transformation via the DOM extension. Let’s review the code in detail (I also have included some comments in the code listing itself).
Many of the DOM XSLT functions deal with the creation, deletion, and modification of DomDocument objects. The first function that is used is the domxml_open_file function. This function creates a DOM object from the provided XML file. The next function you call is the domxml_xslt_stylesheet_file, which creates a new DomXsltStylesheet object. This object will be used later in the transformation of the XML and XSLT document, which creates the HTML output.
Next is the process function of the DomXsltStylesheet object. The process function takes one or more arguments; the first argument must be the DomDocument object. This applies the XSLT transformation on the DomDocument that is passed to it. Additional arguments can be passed to the process function, which can be additional XSLT parameters (array) or Xpath parameters (Boolean). This gives flexibility to the transformation process. The function then returns a DomDocument object that contains the transformed data.
To view the transformed data, the last function provides the result and prints it out to the user. By calling the result_dump_mem function on the tranformation DomDocument $domTranObj object, you can retrieve the output or result of the transformation. This concludes a simple example of how to do XSLT transformation with PHP and DOM XSLT.
Dumping the output
For the second example (Listing D), I’ll introduce a new function namedresult_dump_filewhich dumps the output from the XSLT transformation into a file provided as the second argument to the function. As in the previous example, the first argument is still theDomDocument object created from theDomXsltStylesheet processfunction. Also, I’ve included a parameter to the process function that passes a parameter value to the XSLT processor. This is a demonstration of the ability to control dynamically the XSLT transformation in PHP.
Basic transformation with Sablotron
This third example (Listing E) is the basic transformation using the Sablotron extension. The first function used is the xslt_create. This creates a new Sablotron XSLT processor and returns a resource that you will use to perform the XSLT transformation. Once the Sablotron processor is created you can initiate the transformation. The call to the xslt_process function requires some parameters: the XSLT processor resource, a string XML container, and a string XSL container. There are additional arguments that can be added, like the result container, array arguments, and array parameters. The XML container defaults to a filename that is the document to be processed. The XSL container is the file that will be used to process the XML document. If the result container is included—meaning a filename is provided to the process, then the result of the transformation is stored in that file. If no result container is provided to the process, then the result is returned. In this example, the xslt_process returns the transformation data to the variable $result.
There is a validation section to verify the contents of the $result variable. If the xslt_process fails, then the function returns false, allowing for the verification of the transformation. Notice that if the process is successful, then the data is echoed out to the user. If the transformation fails, then the script terminates with an error message.
One of the reasons I enjoy working with the Sablotron extension is the error functions that it contains. In this example, if an error occurs, then there is a call to two Sablotron functions: xslt_errno, xslt_error. xslt_errno returns an error number from the last error that occurred for the XSLT resource. xslt_error returns an error string that describes the last error message from the XSLT processor. After the validation and simple error handling, there is a call to the xslt_free function. This function takes the XSLT resource as an argument and frees it up.
Encodings and logging with Sablotron
The fourth and final example (Listing F) demonstrates the ability in Sablotron to pass parameters to the xslt_processfunction. This allows the XSLT processor to receive a date that is passed in during the transformation. The example also includes two additional functions: xslt_set_log and xslt_set_encoding. With the xslt_set_log function, you turn logging on by setting the second parameter to “true”. A second call to the function with a second parameter set to a file name completes the logging of all Sablotron XSLT processing messages. Note that these messages do not include errors from the XSLT processor, but provide valuable debugging information regarding the state of the processor during the transformation process.
The xslt_set_encoding sets the output encoding of the Sablotron transformations. However, in order to use this function, the Sablotron extension needs to be compiled with the encoding support. For this example, I set the output to the ISO-8859-2 encoding.