DarCas Sandbox

SOAP (inizialmente acronimo di Simple Object Access Protocol) è un protocollo leggero per lo scambio di messaggi tra componenti software, tipicamente nella forma di componentistica software. La parola object manifesta che l’uso del protocollo dovrebbe effettuarsi secondo il paradigma della programmazione orientata agli oggetti.

Dalla versione 1.2 dello standard, il W3C ha completamente cancellato l’acronimo. Perciò, tecnicamente, l’acronimo SOAP oggi sta per… SOAP!

Il protocollo SOAP è legato all’XML inquanto ogni messaggio inviato o ricevuto da una server SOAP cosiste in una serie di informazioni organizzate in XML.

Un SOAP Web service viene definito grazie all’impiego di un particolare documento, anch’esso XML: il Web Service Description Language (WSDL, pronunciato “whisdl“). Questo file ha il compito di descrivere tutte le funzioni che il web service mette a disposizione.

Come si fa ad accedere ad un Web Service SOAP-based?

Da PHP 5 esiste una nuova classe di funzioni che fa tutto il “lavoro sporco” e mette a disposizioni, come semplici metodi di una classe, le varie interfacce che il web service stesso mette a disposizione.

La classe in questione è la SoapClient e l’esempio seguente chiarirà ogni dubbio sul suo funzionamento. Prendere in esame, come caso studio, l’interfacciamento al web service SOAP di Google per effettuare le ricerche.

Attualmente il web service di Google è disponibile a questo indirizzo http://api.google.com/GoogleSearch.wsdl. Per utilizzarlo occorre avere una key che, nel momento in cui scrivo, non è possibile richiedere.

try { $gKey = ""; # (string) LA NOSTRA KEY PER UTILIZZARE IL SERVIZIO $searchQuery = ""; # (string) QUERY DI RICERCA $startIndex = 0; # (int) RISULTATO DA CUI INIZIARE A STAMPARE $endIndex = 10; # (int) RISULTATI PER PAGINA (MAX 10) $filter = true; # (bool) ELIMINA I RISULTATI DUPLICATI $restrict = ""; # (string) CIRCOSCRIVE I RISULTATI AD UN PARTICOLARE TLD $lr = ""; # (string) LINGUAGGIO DEI RISULTATI $ie = ""; # (string) CODIFICA PER LA REQUEST $oe = ""; # (string) CODIFICA PER LA RISPOSTA $gsearch = new SoapClient('http://api.google.com/GoogleSearch.wsdl'); $result = $gsearch->doGoogleSearch($gKey, $searchQuery, $startIndex, $endIndex, $filter, $restrict, $lr, $ie, $oe); print_r($result); unset($gsearch); } catch (SoapFault $e) { print_r($e); }

Come si può vedere dal codice, nel costrutto della classe va indicato il percorso del file WSDL. La classe analizzerà e renderà poi disponibili tutte le interfacce come semplici metodi della classe.

Come facciamo a sapere tutti i metodi (o interfacce) messi a disposizione del web service? Basta utilizzare un metodo della classe SoapClient, __getFunctions(), che restituisce un array di tutte le funzioni disponibili.

try { $gsearch = new SoapClient('http://api.google.com/GoogleSearch.wsdl'); print_r($gsearch->__getFunctions()); unset($gsearch); } catch (SoapFault $e) { print_r($e); }

La classe SoapClient supporta anche quei web server che non hanno un file WSDL che descrive le proprie funzionalità. In questo caso però non sarà possibile utilizzare le funzioni di introspezione (__getFunctions(), ad esempio), ma occorrerà conoscere i metodi da evocare.

Per istanziare un servizio di questo tipo va modificato leggermente il costrutto, come segue.

$foo = new SoapClient(NULL, 'http://example.com/foo.php');

In rete sono tantissimi i servizi basati su SOAP, molti dei quali gratuiti e con funzionalità interessanti. PHP 5 oggi offre uno strumento potente per poter interagire con essi.