NuSOAP este o colecţie de clase PHP care permite utilizatorilor trimiterea şi recepţionarea de mesaje SOAP folosind protocolul HTTP. NuSOAP, cunoscut şi ca SOAPx4, este distribuit de Corporaţia NuSphere (http://www.nusphere.com). Aceasta librărie este open source, licenţiata sub GNU LGPL. NuSOAP este utilizată ca şi nucleu al altor librarii precum PEAR-SOAP.

Unul dintre avantajele NuSOAP este reprezentat de faptul ca nu este o extensie a PHP, şi este scris exclusiv in acest limbaj. Aceasta înseamnă ca poate fi folosit de către orice dezvoltator PHP, indiferent de restricţiile privind accesul la resursele serverului.

Interacţiunea cu serviciile web este realizata prin intermediul clasei soap_client. Aceasta clasa de nivel înalt permite utilizatorilor sa specifice opţiuni precum autorizarea prin HTTP, informaţii despre proxy HTTP, precum şi gestionarea trimiterii si primirii de mesaje SOAP.

Operaţiile SOAP pot fi executate prin pasarea numelui operaţii care se doreşte a fi executate, funcţiei call(). Daca serviciul oferă un fişier WSDL atunci, clasa soap_client preia URL-ul fişierului WDSDL ca argument in constructor, şi utilizează clasa wsdl pentru a parsa informaţia din fişierul WSDL şi a extrage datele.

Clasa soap_client foloseşte aceste date din fişierul WSDL pentru a encoda parametrii şi pentru a crea un “înveliş” SOAP când userul executa un apel al serviciului. Când apelul este executat, clasa soap_client utilizează clasa soap_transport_http pentru a trimite mesajul şi pentru a pentru a primi răspuns. Mesajul-răspuns este parsat de clasa soap_parser. Figura de mai jos descrie procesul consumării unui serviciu web utilizând NuSOAP.

Structura librariei nuSOAP

Însa daca serviciul web nu oferă un fişier WSDL, procesul este diferit. URL-ul serviciului este transmis constructorului clasei soap_client. Operaţiile sunt executate tot folosind apelul funcţiei obiectului soap_client, dar detaliile care erau oferite in cazul precedent de fişierul WSDL trebuie transmise acum ca argumente. Parametrii care sunt de tip special pot fi reprezentate folosind clasa soapval, care permite utilizatorilor sa-i personalizeze.
Atât SOAP cat şi WSDL folosesc tipurile de date descrise in specificaţiile XML. Acest lucru poate fi problematic deoarece PHP nu suporta nativ tipurile de date definite in specificaţii. De asemenea, tipurile de date in XML sunt stricte şi bine definite in timp ce PHP este un limbaj de programare mult mai permisiv, care converteşte automat tipurile de date in funcţie de situaţie. NuSOAP rezolvă aceasta problema pe trei nivele diferite:

  • In WSDL, clasa soap_client a NuSOAP va encoda tipul valorilor corespunzător tipului specificat in documentul WSDL.
  • Clasa soapval din NuSOAP permite utilizatorilor sa definească explicit tipul valorii
  • Daca nici un tip nu este declarat explicit la instanţierea obiectului soapval, NuSOAP va analiza valoarea atribuita acestuia folosind funcţiile interne ale PHP şi o va clasifica ca tip de date valid XML.

123123.jpg

Modul de utilizare a clasei NuSOAP

Următorul exemplu demonstrează procesul de baza al creării unui client SOAP, apelul unui serviciu şi transmiterea parametrilor, şi recepţionarea mesajului.
Următorul exemplu reprezintă serverul care implementează serviciul Hello.

Server:

//Includerea librariei NuSOAP
include("nusoap.php");

//Crearea instantei de server
$server = new soap_server;

//Inregistrareametodei
$server->register("hello");

//Definirea metodei ca functie PHP
function hello($name){
if(is_string($name)){
return "Hello, " . $name;
} else {
return new soap_fault("Client","","Parametrul transmis serviciului trebuie sa fie string!");
}
}

$raw_post = file_get_contents("php://input");
$server -> service($raw_post);

Pentru a permite funcţiei sa fie apelata la distanta, aceasta trebuie înregistrata in obiectul server. Daca acest lucru nu se realizează atunci, la apelul funcţiei de către client, serverul va genera o eroare, indicând faptul ca serviciul nu este disponibil. In absenta acestui proces de înregistrare, orice funcţie PHP poate fi disponibila apelului la distanta, ceea ce conduce la probleme grave de securitate.
In cazul in care parametrul transmis funcţiei nu este un sir de caractere se generează o eroare in care se specifica problema. Acesta sarcina revine clasei soap_fault, care se ocupa de tratarea erorilor şi transmiterea acestora in mesajul-răspuns.
Pasul final este reprezentat de apelul metodei service, care procesează cererea primita şi apelează funcţia corespunzătoare. Apoi aceasta formulează răspunsul şi îl printeaza.

Client:

// Se instantiaza obiectul soap_client. URL-ul serverului se transmite ca argument in constructor
$client = new soap_client("http://www.w2w.ro/ws_server/hello");
//Parametrii trebuie transmisi printr-un array  clientului SOAP
$param = array("name" => "Dobre Marian");
// Apelul metodei SOAP
$result = $client->call("hello", $param);
if($client->fault){
echo "
<h2>Fault</h2>
<pre>";
print_r($result);
echo "</pre>
";
} else {
$err = $client->getError();
if ($err) {
// Afisarea erorilor
echo "
<h2>Error</h2>
<pre>" . $err . "</pre>
";
} else {
// Afisarea rezultatului
echo "
<h2>Result</h2>
<pre>";
print_r($result);
echo "</pre>
";
}
}
echo "
<h2>Request</h2>
";
echo "
<pre>" . htmlspecialchars($client->request, ENT_QUOTES) . "</pre>
";
echo "
<h2>Response</h2>
";
echo "
<pre>" . htmlspecialchars($client->response, ENT_QUOTES) . "</pre>
";

La apelul metodei call() se specifica obiectului soap_client serviciul care se doreşte a fi accesat, apoi se transmite un array cu parametrii, iar metoda returnează răspunsul serverului. Acest răspuns este un tip de date nativ PHP, precum un string, integer sau array.
NuSOAP oferă un mecanism de detecţie al erorilor prin intermediul metodei getError() . Daca a apărut o eroare, aceasta metoda returnează un string care descrie eroarea, sau returnează false in caz de succes. In exemplul prezentat se va printa rezultatul in cazul in care nu a fost generata nici o eroare. Altfel, se va printa mesajul de eroare.

Ultima parte a codului este foarte utila pentru procesul de debug al operaţiilor efectuate de NuSOAP. Proprietăţile request şi response ale clasei soap_client conţin mesajele, inclusiv headerele HTTP transmise de fiecare.