xslt_process

(PHP 4 >= 4.0.3)

xslt_process — Führt eine XSLT-Transformation durch

Beschreibung

mixed xslt_process ( resource $xh , string $xmlcontainer , string $xslcontainer [, string $resultcontainer [, array $arguments [, array $parameters ]]] )

Die Funktion xslt_process() ist die Krux der XSLT-Extension. Sie erlaubt es Ihnen, eine XSLT-Transformation unter Verwendung von fast jeder Art von Eingabequelle durchzuführen - den Containern. Dies wird durch die Verwendung von Argument-Buffern erreicht, einem Konzept, das vom Sablotron-XSLT-Prozessor übernommen wurde (derzeit der einzige XSLT-Prozessor, den diese Extension unterstützt). Die Input-Container enthalten standardmäßig einen Dateinamen, der für die zu prozessierende Datei steht.

Parameter-Liste

xh: Der XSLT-Prozessor-Linkidentifier, der mittels xslt_create() erzeugt wurde.
xmlcontainer: Pfad zur XML-Datei oder Platzhalter für ein XML-Argument.
xslcontainer: Pfad zur XSL-Datei oder Platzhalter für ein XML-Argument.
resultcontainer: Der Result-Container enthält standardmäßig den Dateinamen des transformierten Dokuments. Wenn der Result-Container nicht angegeben wurde (also NULL ist), wird das Ergebnis zurückgegeben.
arguments: Anstelle von Dateien können Sie auch "Argument-Platzhalter" als XML- oder XSLT-Argumente an xslt_process() übergeben. Diese Platzhalter werden durch die im arguments-Array angegebenen Werte ersetzt.
parameters: Ein Array von aller Toplevel-Parameter, die an das XSLT-Dokument übergeben werden sollen. Auf diese Parameter können Sie in Ihren XSL-Dateien unter Verwendung einer <xsl:param name="parameter_name">-Anweisung zugreifen. Die Parameter müssen UTF-8-kodiert sein, ihre Werte werden vom Sablotron-Prozessor als Strings interpretiert. Mit anderen Worten, Sie können keine Node-Sets als Parameter an ein XSLT-Dokument übergeben.

Container können außerdem mittels des arguments-Arrays bestimmt werden (siehe unten).

Rückgabewerte

Gibt bei Erfolg TRUE zurück. Im Fehlerfall wird FALSE zurückgegeben. Wenn der Result-Container nicht angegeben wurde (also z.B. NULL ist), wird das Ergebnis zurückgegeben.

Changelog

Version	Beschreibung
4.0.6	Die Funktion akzeptiert nicht länger Strings in `xmlcontainer` und `xslcontainer`. Die Übergabe von XML-enthaltenden Zeichenketten an einen der beiden Parameter erzeugt einen Speicherzugriffsfehler in Sablotronversionen bis inklusive 0.95.

Beispiele

Die einfachste Art einer Transformation mit der xslt_process()-Funktion ist die Transformation eines XML-Files durch ein XSLT-File und die Speicherung des Ergebnisses in eine dritte Datei, die das neue XML- (oder HTML-)Dokument enthält. Dies mit Sablotron zu tun ist mehr als einfach.

Beispiel #1 Verwendung von xslt_process(), um eine XML-Datei und eine XSL-Datei in ein neues XML-File zu transformieren


<?php

// Einen neuen XSLT-Prozessor erstellen
$xh = xslt_create();

// Das Dokument verarbeiten
if (xslt_process($xh, 'sample.xml', 'sample.xsl', 'result.xml')) {
    echo "ERFOLG, sample.xml wurde durch sample.xsl in result.xml transformiert";
    echo ", result.xml hat folgenden Inhalt\n<br />\n";
    echo "<pre>\n";
    readfile('result.xml');
    echo "</pre>\n";
} else {
    echo "Sorry, sample.xml konnte nicht von sample.xsl in result.xml ";
    echo "transformiert werden. Fehlermeldung: " . xslt_error($xh) . " und ";
    echo "Fehlernummer: " . xslt_errno($xh);
}

xslt_free($xh);

?>

Obwohl diese Funktion in den meisten Fällen, besonders im Webumfeld, hervorragend läuft, sollten Sie dennoch davon absehen, Ihre Ergebnisse direkt auszugeben. Daher ist es geschickter, das dritte Argument der xslt_process()-Funktion wegzulassen (oder dem Argument NULL zu übergeben) und damit den Rückgabewert der XSLT-Transformation zu erhalten, statt ihn in eine Datei zu schreiben.

Beispiel #2 Verwendung von xslt_process(), um eine XML-Datei und eine XSL-Datei zu transformieren und einer Variable die resultierenden XML-Daten zuzuweisen


<?php

// Einen neuen XSLT-Prozessor erstellen
$xh = xslt_create();

// Dokument verarbeiten, Rückgabe des Ergebnisses an die $result-Variable
$result = xslt_process($xh, 'sample.xml', 'sample.xsl');
if ($result) {
    echo "ERFOLG, sample.xml wurde durch sample.xsl in die Variable \$result ";
    echo "transformiert, die Variable \$result hat folgenden Inhalt\n<br />\n";
    echo "<pre>\n";
    echo $result;
    echo "</pre>\n";
} else {
    echo "Sorry, sample.xml konnte nicht von sample.xsl in die Variable \$result ";
    echo "transformiert werden. Fehlermeldung: " . xslt_error($xh) . " und ";
    echo "Fehlernummer: " . xslt_errno($xh);
}

xslt_free($xh);

?>

Die oberen zwei Fälle sind die einfachsten Fälle die es gibt, wenn eine XSLT-Transformation durchgeführt werden soll. Unseres Erachtens sind sie sogar die häufigsten Fälle; allerdings erhalten Sie auch häufig Ihr XML- und XSLT-Daten aus externen Quellen wie Datenbanken oder Sockets. In diesen Fällen befinden sich die XML- und/oder die XSLT-Daten in einer Variablen - und in Anwendungen, die produktiv eingesetzt werden, erzeugt es zu viel Overhead, diese Daten vor ihrer Verarbeitung erst in eine Datei zu schreiben. An dieser Stelle kommt die XSLT-"argument"-Syntax zum Tragen. Anstatt Dateien als XML- und XSLT-Argumente an xslt_process() zu übergeben, können Sie "Argumentplatzhalter" angeben, die durch die im Argument-Array übergebenen Werte ersetzt werden (der fünfte Parameter der Funktion xslt_process()). Nachfolgend zeigen wir in einem Beispiel, wie XML und XSLT verarbeitet und das Ergebnis in eine Variable geschrieben wird, ohne eine Datei zu verwenden.

Beispiel #3 Verwendung von xslt_process(), um eine XML-Daten enthaltende Variable und eine XSL-Daten enthaltende Variable in eine Variable zu transformieren, die die resultierenden XML-Daten enthält


<?php
// $xml und $xsl enthalten die XML- und XSL-Daten

$arguments = array(
     '/_xml' => $xml,
     '/_xsl' => $xsl
);

// Einen neuen XSLT-Prozessor erzeugen
$xh = xslt_create();

// Dokument verarbeiten
$result = xslt_process($xh, 'arg:/_xml', 'arg:/_xsl', NULL, $arguments);
if ($result) {
    echo "ERFOLG, sample.xml wurde durch sample.xsl in die Variable \$result ";
    echo "transformiert, die Variable \$result hat folgenden Inhalt\n<br />\n";
    echo "<pre>\n";
    echo $result;
    echo "</pre>\n";
} else {
    echo "Sorry, sample.xml konnte nicht von sample.xsl in die Variable \$result ";
    echo "transformiert werden. Fehlermeldung: " . xslt_error($xh) . " und ";
    echo "Fehlernummer: " . xslt_errno($xh);
}
xslt_free($xh);
?>

Beispiel #4 PHP-Variablen an die XSL-Dateien übergeben


<?php

// XML-String
$xml = '<?xml version="1.0"?>
<para>
 ändere mich
</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="/">
Meine PHP-Variable: <xsl:value-of select="$myvar"/><br />
Mein Node-Set: <xsl:value-of select="$mynode"/>
 </xsl:template>
</xsl:stylesheet>';


$xh = xslt_create();

// der zweite Parameter wird als String interpretiert
$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);

?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Meine PHP-Variable: test<br>
Mein Node-Set: &lt;foo&gt;bar&lt;/foo&gt;

Anmerkungen

Hinweis:
Wenn Sie Windows verwenden, beachten Sie bitte, vor Pfadangaben file:// zu schreiben.