xslt_process

(PHP 4 >= 4.0.3)

xslt_process — Realizar una transformación XSLT

Descripción

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

La función xslt_process() es crucial para la extensión XSLT. Permite realizar una transformación XSLT empleando casi cualquier tipo de origen de entrada: los contenedores. Esto se realiza a través del uso de búferes de argumentos, un concepto tomado del procesador de XSLT Sablotron (actualmente el único procesador de XSLT que admite esta extensión). El valor predeterminado para los contenedores de entrada es un nombre de fichero que 'contiene' el documento a procesar.

Parámetros

xh: El identificador de enlace del procesador de XSLT, creado con xslt_create().
xmlcontainer: La ruta al fichero XML o el parámetro de sustitución para el argumento XML.
xslcontainer: La ruta al fichero XSL o el parámetro de sustitución para el argumento XML.
resultcontainer: El valor predeterminado para el contenedor resultante es un nombre de fichero para el documento transformado. Si el contenedor resultante no se especifica -es decir, NULL- se devuelve el resultado.
arguments: En vez de especificar ficheros para los argumentos XML y XSLT de la función xslt_process(), se pueden especificar "parámetros de sustitución de argumentos" que serán sustituidos por los valores dados en el array arguments.
parameters: Un array para cualquier parámetro del más alto nivel que será pasado al documento XSLT. Se puede acceder a estos parámetros dentro de los ficheros XSL empleando la instrucción <xsl:param name="nombre_parámetro">. Los parámetros deben estar codificados en UTF-8 y sus valores ser interpretados como string por el procesador Sablotron. En otras palabras, no se pueden pasar conjuntos de nodos como parámetros al documento XSLT.

Los contenedores también se pueden establecer mediante el array arguments (véase más abajo).

Valores devueltos

Devuelve TRUE en caso de éxito o FALSE en caso de error. Si no se especifica el contenedor resultante -es decir, NULL- se devuelve el resultado.

Historial de cambios

Versión	Descripción
4.0.6	Esta función ya no toma un string con XML en `xmlcontainer` o `xslcontainer`. Pasar un string que contiene XML a cualquiera de estos parámetros resultará en un error de segmentación en versiones de Sablotron hasta e incluyendo la 0.95.

Ejemplos

El tipo de transformación más sencilla con la función xslt_process() es la transformación de un fichero XML con un fichero XSLT, colocando el resultado en un tercer fichero que contiene el nuevo documento XML (o HTML). Hacer esto con Sablotron es realmente sencillo...

Ejemplo #1 Usar xslt_process() para transformar un fichero XML y un fichero XSL en un nuveo fichero XML


<?php

// Asignar un nuevo procesador de XSLT
$xh = xslt_create();

// Procesar el documento
if (xslt_process($xh, 'muestra.xml', 'muestra.xsl', 'resultado.xml')) {
    echo "ÉXITO, muestra.xml se transformó mediante muestra.xsl en resultado.xml";
    echo ", resultado.xml contiene lo siguiente:\n<br />\n";
    echo "<pre>\n";
    readfile('resultado.xml');
    echo "</pre>\n";
} else {
    echo "Lo sentimos, muestra.xml no se pudo transformar mediante muestra.xsl en";
    echo " resultado.xml; la razón es: " . xslt_error($xh) . ", y el";
    echo " código de error es " . xslt_errno($xh);
}

xslt_free($xh);

?>

Aunque esta es una gran funcionalidad, muchas veces, especialmente en un entorno web, se querrá imprimir el resultado directamente. Por lo tanto, si se omite el tercer argumento de la función xslt_process() (o se proporciona un valor NULL para dicho argumento), automáticamente devolverá el valor de la transformación XSLT, en lugar de escribirla en un fichero...

Ejemplo #2 Usar xslt_process() para transformar un fichero XML y un fichero XSL en una variable que contiene los datos XML resultantes


<?php

// Asignar un nuevo procesador de XSLT
$xh = xslt_create();

// Procesar el documento, devolviendo el resultado en la variable $resultado
$resultado = xslt_process($xh, 'muestra.xml', 'muestra.xsl');
if ($resultado) {
    echo "ÉXITO, muestra.xml se transformó mediante muestra.xsl en la variable";
    echo " \$result; la variable \$resultado continene lo siguiente:\n<br />\n";
    echo "<pre>\n";
    echo $resultado;
    echo "</pre>\n";
} else {
    echo "Lo sentimos, muestra.xml no se pudo transformar mediante muestra.xsl en";
    echo " la variable \$resultado; la razón es: " . xslt_error($xh);
    echo " y el código de error es " . xslt_errno($xh);
}

xslt_free($xh);

?>

Los dos casos anteriores son los más sencillos que existen para usar transformaciones XSLT, y me atrevo a decir que son los casos más comunes; sin embargo, algunas veces se obtiene el código XML y XSLT desde fuentes externas, como una base de datos o un socket. En estos casos se tendrán los datos XML y/o XSLT en una variable, por lo que, en aplicaciones de producción, la sobrecarga de depositar dichos datos en un fichero podría ser excesiva. Aquí es cuando la sintaxis de "argumentos" de XSLT viene al rescate. En vez de pasar ficheros a los argumentos XML y XSLT de la función xslt_process(), se pueden especificar "parámetros de sustitución de argumentos", los cuales son sustituidos por los valores dados en el array de argumentos (5º parámetro de la función xslt_process()). El siguiente es un ejemplo de tranformación de XML y XSLT en una variable de resultados sin emplear ningún fichero.

Ejemplo #3 Usar xslt_process() para transformar una variable que contiene datos XML y una variable que contiene datos XSL en una variable que contiene los datos XML resultantes


<?php
// $xml y $xsl contienen los datos XML y XSL

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

// Asignar un nuevo procesador de XSLT
$xh = xslt_create();

// Procesar el documento
$resultado = xslt_process($xh, 'arg:/_xml', 'arg:/_xsl', NULL, $argumentos);
if ($resultado) {
    echo "ÉXITO, muestra.xml se transformó mediante muestra.xsl en la variable";
    echo " \$result; la variable \$resultado continene lo siguiente:\n<br />\n";
    echo "<pre>\n";
    echo $resultado;
    echo "</pre>\n";
} else {
    echo "Lo sentimos, muestra.xml no se pudo transformar mediante muestra.xsl en";
    echo " la variable \$resultado; la razón es: " . xslt_error($xh);
    echo " y el código de error es " . xslt_errno($xh);
}
xslt_free($xh);
?>

Ejemplo #4 Pasar variables de PHP a ficheros XSL


<?php

// String XML
$xml = '<?xml version="1.0"?>
<para>
 cámbiame
</para>';

// String XSL
$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="mivar"/>
 <xsl:param name="minodo"/>
 <xsl:template match="/">
Mi variable de PHP : <xsl:value-of select="$mivar"/><br />
Mi conjunto de nodos : <xsl:value-of select="$minodo"/>
 </xsl:template>
</xsl:stylesheet>';


$xh = xslt_create();

// el segundo parámetro será interpretado como un string
$parámetros = array (
  'mivar' => 'test',
  'minodo' => '<foo>bar</foo>'
);

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

echo xslt_process($xh, 'arg:/_xml', 'arg:/_xsl', NULL, $argumentos, $parámetros);

?>

El resultado del ejemplo sería:

Mi variable de PHP : test<br>
Mi conjunto de nodos : &lt;foo&gt;bar&lt;/foo&gt;

Notas

Nota:
Observe que es necesario poner file:// delante de la ruta al utilizar Windows.