Expériences

Présentation - Objectifs

Le but de ce tutoriel est de fournir une première approche de la création de services web (WebServices) en PHP, version 5, à l’aide de la librairie nuSOAP. Je ne rentrerai pas dans les détails concernant les Web Services. Je consacrerai à ces derniers un article spécial ou des liens intéressants dans un coin. Pour comprendre cet article, il est nécessaire d’avoir des bases en PHP, XML et Web Service (SOAP : Simple Object Access Protocol).

À la fin de ce tutoriel, vous serez capables - je l’espère - de créer votre propre service web en PHP, et également de l’utiliser.

Création d’un Web Service

Avant toute chose, vous allez avoir besoin de la librairie nuSOAP, disponible ici. Il s’agit d’une bibliothèque qui fournit des méthodes qui permettent de créer un serveur ou un client SOAP. Pour la création d’un client, il peut y avoir des conflits entre le nom de la classe nuSOAP soapclient et des classes dans les librairies natives de PHP. Si c’est le cas, renommez soapclient en soap_client (par exemple) dans tous les fichiers de la librairie nuSOAP.

Création de la méthode du service

Créez un fichier, service.php par exemple, qui correspondra au Web Service. Écrivez une méthode PHP que vous voudrez exporter, par exemple sayHello. Cette méthode prend en paramètre un prénom et renvoie une chaîne de bienvenue :

function sayHello($name) {
    return "Bienvenue ".$name;
}

Enregistrement du service

Il suffit maintenant d’enregistrer cette méthode en tant qu’opération de Web Service. Pour cela, on inclut le fichier principal de nuSOAP. Ce dernier permet de créer un objet de type soap_server, qui va permettre, à l’aide de la méthode register, d’enregistrer notre méthode sayHello.

// Inclusion de la librairie NuSOAP
require_once("nusoap/lib/nusoap.php");

// Définition de la méthode sayHello
function sayHello($name) {
    return "Bienvenue ".$name;
}

// Création du service
$server = new soap_server; 

// Enregistrement de la méthode
$server->register('sayHello');
?>

Traitement des requêtes SOAP

Pour terminer, il va falloir traiter les requêtes des clients. On appelle la méthode service de l’objet soap_server en lui passant le contenu de la requête. Le fichier service.php permet donc à la fois de construire le Web Service et de traiter les requêtes client. On rajoute ainsi au fichier service.php :

// Invoque le service
$requete_HTTP_brute = (isset($HTTP_RAW_POST_DATA)?$HTTP_RAW_POST_DATA:'');
$server->service($requete_HTTP_brute);

Les Web Services sont indépendants du protocole de communication. Dans le cas des sites web, le protocole est généralement HTTP. PHP traite les requêtes HTTP des clients (fournies par le serveur web) et permet d’accéder directement aux données “intéressantes” (variables GET et POST) de cette requête. Cependant, dans le cas d’un Web Service, la requête ne suit pas le protocole HTTP mais le protocole SOAP. C’est alors la méthode service qui va analyser cette requête et, en l’occurence, renvoyer le résultat, également sous format SOAP. PHP permet d’avoir accès à la requête brute par l’intermédiaire de la variable $HTTP_RAW_POST_DATA. Il faut cependant parfois modifier la configuration always_populate_raw_post_data (la mettre à la valeur On) du fichier php.ini.

Test du service

Il ne reste plus qu’à tester le service. Rendez-vous à l’adresse correspondant au fichier service.php (http://localhost/testnusoap/service.php par exemple). Vous devriez alors voir le message :

    
        Client
        
        method '' not defined in service
        
    

Il s’agit d’un message d’erreur au format SOAP qui indique qu’aucune méthode du service n’a été spécifiée par le client : votre service fonctionne a priori. Nous allons tester maintenant la méthode sayHello en écrivant un client pour le Web Service.

Accès à un Web Service

Il existe plusieurs solutions en PHP pour accéder à un Web Service. La bibliothèque nuSOAP en fournit une, mais il existe des méthodes et objets natifs en PHP5 que je ne developperai pas ici.

Dans un fichier séparé, test-sayHello.php par exemple, nous allons créer un client SOAP. Pour cela, il faut indiquer l’adresse du service :

<

Code de création du client SOAP

On va maintenant appeler la méthode sayHello du service. Pour cela, on fournit le nom de la méthode et les paramètres de cette méthode :

// Appel de la méthode sayHello du service
$response = $client->call('sayHello', array(
    'name'	=> "Michel"
    ));

?>

L’objet $response contient alors la réponse SOAP. Si nous l’affichons à l’aide de var_dump($response);, nous obtenons pour l’exemple de la méthode sayHello :

string(16) "Bienvenue Michel"

Pour aller plus loin

Ce tutoriel n’aborde pas l’API nuSOAP en profondeur. Pour plus d’informations, référez-vous à la documentation de l’API.

Nous avons été tout de même en mesure de créer un WebService et de l’utiliser grâce à la librairie nuSOAP qui permet d’abstraire largement le protocole SOAP. Il est évidemment possible d’agrémenter notre service d’autres méthodes, en utilisant le même principe. Comme nous l’avons vu, SOAP prévoit un système d’erreur spécifiques (les Fault). La librairie nuSOAP permet de gérer ces erreurs, notamment en vérifiant le type de la réponse et en utilisant le champ fault de cette réponse. Il est également possible d’afficher les requêtes et réponses SOAP (en XML donc) en utilisant les champs request et response de l’objet soapclient.

La distribution d’un Web Service passe généralement par une description de celui-ci dans un format particulier : WSDL (Web Services Description Language). nuSOAP permet également de générer cette description. Il faut pour cela utiliser la méthode configureWSDL de l’objet soap_server. À l’inverse, il est envisageable de se servir du WSDL d’un service existant pour créer un client SOAP.

Conclusion

Comme vous avez pu le voir, la création d’un Web Service en PHP est relativement simple. Il n’y a en plus que très peu de problèmes rencontrables au niveau de la configuration de l’environnement. Néanmoins, seules les méthodes et fonctions de base ont pour l’instant été abordées. La création d’un Web Service plus complet et complexe pourra être l’objet d’un prochain article.