SOAP con PHP, la libreria NuSOAP

Come premesso all'inizio di questa guida non mi sono proposto di creare una "Guida allo sviluppo" che sarebbe in breve diventata un groviglio di riferimenti a librerie e differenti interpretazioni. Mi sono proposto di creare un "introduzione" (passatemi il termine) al mondo dei servizi web che passi prima di tutto per la conoscenza dell'argomento.

Con l'ausilio di alcune librerie è certamente possibile implementare Web service PHP senza bisogno di conoscere a fondo come sono fatti o come funzionano (vedremo ora un esempio con Flash e PHP) ma per queste cose non era certamente necessaria una guida. Tuttavia conoscere i Web service sarà indispensabile per sviluppare applicazioni più complesse o anche semplicemente eseguire del debug per capire e risolvere eventuali problemi che possono verificarsi.

In questa sezione vedremo finalmente all'opera un Web service sviluppato per mezzo di esempi grazie a PHP e la libreria NuSOAP.

Un Web service tuttavia è quantomeno inutile se non c'è qualche applicazione che lo possa sfruttare. Per semplicità, e per meglio comprende i vantaggi offerti, sfrutteremo il nostro servizio web tramite un client Flash svelando uno dei metodi più interessanti attualmente offerti da questo prodotto per accedere a database e risorse dinamiche.

Per prima cosa definiamo le operazioni che il nostro Web service deve effettuare. Scegliamo qualcosa di semplice e già visto in precedenza: un operazione che riceve in input un id restituisce le caratteristiche dell'utente trovato.

Cominciamo includendo la libreria NuSOAP all'interno del nostro file PHP, non prima di averla scaricata dal sito del progetto. Poiché il codice non è molto ed è piuttosto semplice da comprendere lo descrivo per mezzo di adeguati commenti.

<?php
	//includiamo la libreria NuSOAP
	require_once("nusoap.php");
	//definiamo il nostro namespace privato come abbiamo fatto anche nel capitolo WSDL
	define("NAMESPACE", "https://www.html.it/guida_ai_Web services");
	//creiamo un istanza del server fornito da nusoap
	$server = new soap_server;
	//disattiviamo il debug
	$server->debug_flag=false;

Cominciamo a configurare un documento WSDL (che sarà elaborato da NuSOAP) per il nostro Web service

// diamo un nome al Web service ed impostiamo il nostro namespace
	$server->configureWSDL('GestioneUtenti', NAMESPACE); 
	// impostiamo il nostro namespace anche come target dello schema WSDL (come abbiamo fatto nell'esempio WSDL)
	$server->wsdl->schemaTargetNamespace = NAMESPACE;

Ora che abbiamo definito le parti personali del WSDL passiamo a definire i tipi, di tutto il resto si occuperà la libreria NuSOAP

// aggiungiamo al WSDL un tipo complesso (li abbiamo già visti in precedenza)
	$server->wsdl->addComplexType(
		'utente',      // con il primo argomento impostiamo il nome
		'complexType', // con il secondo il tipo, naturalmente complesso
		'struct',      // indichiamo a NuSOAP il tipo php che useremo per questo elemento
		'all',         // qui impostiamo l'indicatore di ordine
		'',            // attraverso questo argomento si può impostare una restrizione
                       // ma noi non ne abbiamo bisogno
		// con questo array inseriamo gli elementi child (figli)
		// che faranno parte dell'elemento utente
		array(
			 // sono elementi di tipo semplice, impostiamo per loro il nome ed il tipo
			'nickname' => array('name'=>'nickname','type'=>'xsd:string'), 
			// N.B. in NuSOAP il namespace per i tipi base è xsd,
			// nei nostri esempi precedenti noi avevamo usato xs
			'nome' => array('name'=>'nome','type'=>'xsd:string'),
			'cognome' => array('name'=>'cognome','type'=>'xsd:string'),
			'email' =>array('name'=>'email','type'=>'xsd:string')
		)
	);

Abbiamo definito il tipo utente di cui avevamo bisogno, possiamo definire qualche operazione da rendere disponibile tramite il Web service che stiamo sviluppando o, ancora meglio, le registriamo nel WSDL che stiamo creando con NuSOAP:

$server->register(
		// decidiamo il nome da dare all'operazione
		'getUserById', 
		// questo array contiene gli elementi da ricevere in input
		// per l'operazione, come chiave il nome dell'elemento da
		// ricevere ed il suo tipo come valore
		array('id'=>'xsd:int'), 
		// stessa cosa per questo array che invece rappresenta
		// l'output dell'operazione. n.b. in NuSOAP i tipi da
		// noi creati vengono inseriti nel namespace "tns"
		array('return'=>'tns:utente'), 
		// ancora una volta specifichiamo il namespace
		NAMESPACE
	);

Una volta registrata un'operazione per il Web service bisogna anche implementarla. È estramamente semplice:

// n.b. il nome della funzione dev'essere uguale al nome
	// che abbiamo registrato in precedenza per l'operazione
	function getUserById($id)
	{
		//qui per questo esempio rimane poco da fare...
		// all'interno della funzione puoi fare quello che ti serve,
		// a seconda dello scopo che devi raggiungere
		//Per questo esempio è sufficiente far ritornare qualcosa alla funzione ;)
		$value = Array(
			'nickname' => 'ironoxide',
			'nome' => 'giulio',
			'cognome' => 'giulietti',
			'email' => 'ironoxid@libero.it'
		);
		return $value;
	}

A questo punto non c'è più nulla da fare per noi... lasciamo fare a NuSOAP.

$HTTP_RAW_POST_DATA = isset($GLOBALS['HTTP_RAW_POST_DATA']) ?$GLOBALS['HTTP_RAW_POST_DATA'] : '';
	$server->service($HTTP_RAW_POST_DATA);
	exit();
?>

A cosa serve exit() qui!? Non avevamo detto di far fare tutto a NuSOAP!? Meglio esserne certi! Infatti se scappa qualche output (come un errore o un echo) nel bel mezzo dei messaggi SOAP si inceppa sicuramente in un errore di comunicazione.

Abbiamo descritto tutto il file, pronto per fare da web service. È molto semplice e si comprende facilmente anche con poca esperienza di PHP e poi... dopo aver letto ed aver capito come funziona un web service.. queste sono bazzecole! ;)

Per provarlo in locale puoi scaricare qui il file php completo, altrimenti puoi utilizzare il progetto completo disponibile in allegato. Vedrai con piacere che NuSOAP ha anche un'utile funzione di documentazione.

Per raggiungere il documento WSDL vero e proprio basta aggiungere al nome del file la stringa ?wsdl (quindi "esempio.php" diviene "esempio.php?wsdl") oppure seguire il link nella documentazione.