Como devolver arreglos y estructuras de datos en SOAP transparentemente, utilizando PHP y NuSOAP

¡Saludos nuevamente blogueros!

En este artículo veremos como resolver una duda que apareció hace un tiempo, acerca del envío de datos por servicios web utilizando la biblioteca NuSOAP de PHP. En un artículo pasado, hablamos de como implementar un servicio web desde PHP utilizando esta biblioteca; este servicio contaba con dos métodos, uno de ellos devolvía una cadena y el otro un arreglo asociativo de PHP, se pudo consumir el servicio desde un cliente AJAX sin problema procesando el código XML directamente, sin embargo, al trabajar de esta manera se pierde uno de los puntos importantes para utilizar protocolos de comunicación entre aplicaciones: la transparencia. Es decir, al consumir el servicio el cliente no pudo extraer la estructura de datos recibida, sin necesidad de darle un tratamiento al XML de la respuesta y teniendo que saber de antemano cuál era la estructura XML que recibiría.

Ahora, la idea es corregir este problema de transparencia, al mismo tiempo que mostramos como mandar diferentes tipos de datos complejos, como son: estructuras, arreglos y arreglos de estructuras.

Manos a la obra

Para poder llegar a este nivel de transparencia entre aplicaciones es que el protocolo SOAP utiliza el WSDL, el cual además de contener la definición de cada uno de los métodos que posee un servicio web, puede tener también la definición de tipos de datos complejos. Un tipo de dato complejo consiste una colección de valores agrupados dentro de una estructura, y dentro de este tipo de datos es que encontramos los objetos y arreglos.

Podemos definir estos datos complejos utilizando la clase soap_server de la biblioteca NuSOAP. Como recordarán -y si no es así lo menciono- esta clase nos permite crear servicios web en nuestro servidor para que lo consuman los clientes. Dentro de esta clase se encuentra un objeto llamado wsdl, definido como una propiedad de la misma clase, el cual posee una serie de métodos para definir las características del WSDL del servicio web. El método que emplearemos concretamente para definir los nuevos tipos de datos será el addComplexType. El primer paso consistirá en instanciar la clase soap_server de la siguiente forma:

require_once('nusoap.php');
$servidor = new soap_server;

Una vez hecho esto contamos con un objeto de esta clase, para el cual podemos definir sus características:

$ns = "http://nuestroespaciodenombres";
$servidor->configureWSDL('NombreDelServicio',$ns);
$servidor->wsdl->schematargetnamespace = $ns;

Ahora viene lo bueno, definir tipos de datos complejos para que sean devueltos por los métodos de nuestro servicio. Para este ejemplo definiremos 3 estructuras diferentes para probar las posibilidades que nos ofrece esta clase:

• Primero un arreglo de cadenas sencillo:

$servidor->wsdl->addComplexType(
        'ArregloDeCadenas',
        'complexType',
        'array',
        'sequence',
        'http://schemas.xmlsoap.org/soap/encoding/:Array',
        array(),
        array(array('ref' => 'http://schemas.xmlsoap.org/soap/encoding/:arrayType',
         'wsdl:arrayType' => 'xsd:string[]')
        ),
        'xsd:string'  
);

Como vemos, se incluye una referencia(http://schemas.xmlsoap.org/soap/encoding/:Array) a la definición del formato que debe tener un dato de tipo complejo Array.

• Después una estructura de datos, similar a los arreglos asociativos, que contendrá una serie de valores distinguidos por un nombre:




$servidor->wsdl->addComplexType(
        'Estructura',
        'complexType',
        'struct',
        'all',
        '',
        array(
        'Nombre' => array('name' => 'Nombre', 'type' => 'xsd:string'),
        'Apellidos'=>array('name' => 'Apellidos', 'type' => 'xsd:string'),
        'Edad'=>array('name' => 'Edad', 'type' => 'xsd:integer')
        )
);




• Finalmente -y lo más interesante-, un arreglo de estructuras de datos:

$servidor->wsdl->addComplexType(
        'ArregloDeEstructuras',
        'complexType',
        'array',
        'sequence',
        'http://schemas.xmlsoap.org/soap/encoding/:Array',
        array(),
        array(array('ref' => 'http://schemas.xmlsoap.org/soap/encoding/:arrayType',
         'wsdl:arrayType' => 'tns:Estructura[]')
        ),
        'tns:Estructura'  
);

Digo que el último ejemplo me parece el más interesante porque con este podemos definir datos de entrada y de salida para los métodos que consistirán en listas de estructuras de datos, similares a las que encontramos en muchos lenguajes de programación de alto nivel y sobre todo muy útiles para representar registros de bases de datos y archivos estructurados.

Para incluir estos datos de entrada y de salida de los métodos, basta con declararlo en el método registrer donde se declaran los métodos, y asegurarnos por supuesto de que la estructura de los parámetros de estos métodos que hagan referencia los tipos de datos complejos, corresponda con la estructura declarada, es decir:

function consultaPersonas($param) {
    $arreglo = array();
    $arreglo[] = array('Nombre'=>"Juan", 'Apellidos'=>"Torres", 'Edad'=>18);
    $arreglo[] = array('Nombre'=>"Teresa", 'Apellidos'=>"Jiménez Sánchez", 'Edad'=>19);
    $arreglo[] = array('Nombre'=>"Efraín", 'Apellidos'=>"Ovalles López", 'Edad'=>22);
    return $arreglo;
}

$servidor->register('consultaPersonas',
    array('param'=>'xsd:string'),
    array('return'=>'tns:ArregloDeEstructuras'),
    $ns
);

Si por ejemplo creamos un método que devuelva el tipo de dato complejo ArregloDeEstructuras, en el código de nuestro método deberemos incluir una estructura de datos equivalente, en este caso un arreglo asociativo, donde cada llave del arreglo corresponde al identificador de los datos de nuestra estructura previamente definida -llamada Estructura en este ejemplo-; así en el método, cada entrada del arreglo contendrá a la vez un arreglo asociativo, que corresponderá a esta estructura de datos.

De esta forma es posible crear servicios web que devuelvan a nuestras aplicaciones arreglos de estructuras de datos, e incluso arreglos de arreglos, lo cual ayudará a que nuestros servicios puedan generar mayor variedad de datos de salida, y de esta forma aumentaremos el poder las capacidades nuestras aplicaciones. Además de esto, se logra mucha mayor transparencia, ya que cualquier aplicación de terceros o que nosotros mismos desarrollemos, solo tendrá que seguir el formato definido en el WSDL de nuestros servicios web, para poder desentrañar estos tipos de datos complejos. Algunos entornos de desarrollo -como el de .Net- incluso permiten implementar el consumo de estos servicios web interpretando los tipos de datos complejos como objetos nativos del lenguaje, lo que nos permite manipularlos con mucha mayor facilidad, así que las posibilidades son muchas.

Hasta la próxima.

Devolver objetos en JSON desde PHP

Yo digo que es una dona

¡Saludos blogueros!

Ese pequeño artículo va para los que se preguntaban en el ejemplo anterior, ¿qué era ese formato llamado JSON que utiliza flickr para enviarnos la información? Se trata más que nada de una forma para intercambiar datos estructurados entre diferentes sistemas sobre protocolos como HTTP. JSON, define cómo se deberán codificar los objetos de un determinado lenguaje para convertirlos en cadenas de texto, con el propósito de enviarlos hacia otras aplicaciones, y que estas puedan reconstruirlos como objetos nativos, utilizando la decodificación definida por el mismo formato JSON.

Por ejemplo, digamos que mi aplicación desea mandar un objeto que contiene determinada información hacia un cliente Javascript, además de las ya conocidas técnicas basadas en XML o protocolos como SOAP, tenemos la posibilidad de mandarlo codificado en JSON, de modo que desde nuestra aplicación convertiremos ese objeto en una cadena de texto que lo representará, y lo enviaremos a nuestro cliente Javascript como una respuesta en texto simple, el cliente -con previo conocimiento del formato de la respuesta-, solo tendrá que aplicar las reglas de la notación para -partir de la cadena- reconstruir el objeto y utilizarlo dentro de su propia ejecución de instrucciones. Tal y como hicimos en el ejemplo anterior con los servicios de flickr.

La gran ventaja de JSON, es que el cliente Javascript puede utilizar la instrucción eval, para reconstruir el objeto partir de la cadena recibida, sin necesidad de ningún interprete especia, tal y como explica el artículo de la Wikipedia sobre JSON. Del lado de nuestra aplicación en el servidor por otro lado sí se necesitará de una funcionalidad que haga el trabajo de codificar los objetos u arreglos en la notación de JSON, pero para eso la gran mayoría de los lenguajes cuentan ya con bibliotecas de funciones o clases para hacer la tarea.

En este artículo veremos cómo hacer esa tarea del lado del servidor, utilizando la biblioteca de funciones para JSON de PHP, disponible a partir de la versión 5.2.0. Creando la siguiente aplicación web en este lenguaje:

respuestajson.php

<?php

//Clase para representar una serie de diferentes artículos para tiendas

class Articulo {
 public $id;
 public $nombre;
 public $categoria;
 public $precioDeSalida;
 public $detalles;
}



$articulo = new Articulo();
$articulo->id = 1;
$articulo->nombre = "Nintendo DS";
$articulo->categoria = "Videojuego";
$articulo->precioDeSalida = "$3 500";
$articulo->detalles = array('Soporta juegos para Gameboy advance','Pantalla tactil','Reproducción de MP3');
echo json_encode($articulo);?>

El programa en PHP codificara en notación JSON el objeto $articulo, dando como resultado una cadena que devolverá al cliente, la cual podemos visualizar si accedemos a la aplicación desde el navegador (http://localhost/respuestajson.php):

{"id":1,"nombre":"Nintendo DS","categoria":"Videojuego","precioDeSalida":"$3 500","detalles":["Soporta juegos para Gameboy advance","Pantalla tactil","Reproducci\u00f3n de MP3"]}

Ahora, el cliente AJAX para procesar estos datos sería el siguiente:

clientejson.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Decodifica un objeto en JSON</title>
<script type="application/javascript">
var http_request = new XMLHttpRequest();
var url = "http://localhost/respuestajson.php"; // Esta URL debería devolver datos JSON
 
// Descarga los datos JSON del servidor.
http_request.onreadystatechange = manejaJSON;
http_request.open("GET", url, true);
http_request.send(null);

function manejaJSON() {
  if (http_request.readyState == 4) {
    if (http_request.status == 200) {
      var cadCodificadaJSON = http_request.responseText; 
      var objDatos = eval("(" + cadCodificadaJSON + ")"); //Creamos el objeto utilizando la cadena codificada
      //Ahora con el objeto desplegamos los datos mandados desde el servidor
      document.getElementById("divId").innerHTML = objDatos.id;
      document.getElementById("divNombre").innerHTML = objDatos.nombre;
      document.getElementById("divCategoria").innerHTML = objDatos.categoria;
      document.getElementById("divPrecio").innerHTML = objDatos.precioDeSalida;
      document.getElementById("divDetalles").innerHTML = objDatos.detalles[0] + ", " + objDatos.detalles[1] + ", " + objDatos.detalles[2];
    } else {
      alert("Ocurrio un problema con la URL.");
    }
    http_request = null;
  }
}
</script>
</head>
<body>
<h2>Producto</h2>
<div id="divId"></div>
<div id="divNombre"></div>
<div id="divCategoria"></div>
<div id="divPrecio"></div>
<div id="divDetalles"></div>
</body>
</html>

Este código implementa una sencilla aplicación AJAX, similar a las vistas en los primero ejemplos sobre esta tecnología vistos en este blog. Básicamente accede a la aplicación en PHP que creamos previamente, y procesa el texto plano que recibe como respuesta, almacenándolo en la cadena, debido a que este texto consiste en la codificación en JSON del objeto original, lo decodifica utilizando la instrucción eval("(" + cadCodificadaJSON + ")"), creando el objeto objDatos como resultado.

El resultado obtenido se vería en el navegador como sigue:

Producto

1

Nintendo DS

Videojuego

$3 500

Soporta juegos para Gameboy advance, Pantalla tactil, Reproducción de MP3

De esta forma, podemos transmitir conjuntos de datos estructurados sin recurrir a formatos como XML o protocolos como SOAP, que requieren un mayor trabajo de procesamiento de la información en el cliente, pero que en contra parte, exige que el servidor pueda llevar a cabo la codificación de objetos en JSON. La elección final de la forma en que vayamos a transmitir los datos sobre HTTP, dependerá de los requerimientos que nos exijan la arquitectura y la plataforma que habremos de utilizar.

Saludos.