Les derniers articles

Construire un service web en PHP 5 grâce à l'extension SOAP

Date :: 2004-08-11
Last Updated :: 2004-08-11

Introduction
Classes de l'extension SOAP
- soapClient
- soapFault
- soapHeader
- soapParam
- soapServer
- soapVar
Description du service web
Le fichier WSDL
La classe
Mise en place du serveur SOAP
Interroger notre service web (Client)
Conclusion
Liens utiles

Introduction

SOAP est un protocole basé sur XML, qui permet l'échange de données structurées entre applications.
PHP 5 fournit une nouvelle extension, permettant de créer aisémment des clients et serveurs SOAP , basée sur un ensemble de classes de bas niveau. Dans cet article, nous allons donc voir comment créer un service web simple (un serveur SOAP ) et comment interroger ce serveur (un client SOAP ).
Notre service web sera decrit dans un fichier WSDL.

Les classes de l'extension SOAP

Voici une description succincte des classes et des méthodes que fournit l'extension SOAP :

soapClient

Cette classe permet de construire un client SOAP qui permettra d'interroger un service web.
Elle dispose des méthodes membre suivantes :

soapClient :: __construct() :: Constructeur de la classe
soapClient :: __call() :: Appelle une fonction SOAP
soapClient :: __getFunctions() :: Liste les fonctions SOAP disponibles en mode WSDL
soapClient :: __getLastRequest() :: Retourne la dernière requête SOAP
soapClient :: __getLastResponse() :: Retourne la dernière réponse SOAP
soapClient :: __getTypes() :: Retourne la liste des Types SOAP

soapFault

Cette classe sert à renvoyer une erreur SOAP , elle ne dispose pas de méthode hormis son constructeur. ~Elle permet notamment de gérer les exceptions~.

soapHeader

Cette classe permet d'envoyer ou de récupérer des en-têtes SOAP , selon le contexte où elle est appellée (client/serveur). Elle ne dispose pas de méthode hormis son constructeur

soapParam

Cette classe sert à définir des paramètres en mode non WSDL. Elle ne dispose pas de méthode hormis son constructeur

soapServer

Cette classe permet la création de serveur SOAP en mode WSDL ou non, elle dispose des méthodes suivantes :

soapServer :: __construct() :: Constructeur de la classe
soapServer :: addFunction() :: Exporte la, ou les fonctions passées en argument vers le client
soapServer :: getFunctions() :: Liste les fonctions disponibles sur le serveur
soapServer :: handle :: Traite la requète SOAP envoyée par le client et retourne le résultat
soapServer :: setClass() :: Définit la classe qui va traiter les requètes SOAP envoyées au serveur
soapServer :: setPersistence() :: Sauvegarde les données dans une session entre deux requètes

soapVar

Cette classe gère l'encodage des paramètres en mode non WSDL. Elle ne dispose pas de méthode hormis son constructeur

Description du service web

Pour l'exemple, nous allons construire un service web très simple, disposant d'une unique méthode destinée à renvoyer la date courante du serveur. Cette fonctionnalité ne présente aucun intéret, l'exemple est à titre pédagogique, vous pourrez ensuite implémenter les services que vous désirez selon les besoins de votre site, en adaptant le fichier WSDL et la classe PHP.

Le fichier WSDL

Voici notre fichier WSDL qui sert à decrire notre service web. Nous n'entrerons pas ici dans la description de ce fichier, ce n'est pas le but de l'article, néamoins, je vous recommende vivement de lire les spécifications WSDL afin de comprendre le fonctionnement du fichier suivant :

<?xml version="1.0"?>

<definitions name="CSP"
    targetNamespace="urn:CSP"
    xmlns:tns="urn:CSP"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:typens="urn:CSP"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns="http://schemas.xmlsoap.org/wsdl/">

<types>
    <xsd:schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:CSP">
        <xsd:complexType name="MyResults">
            <xsd:all>
                <xsd:element name="date" type="xsd:string"/>
            </xsd:all>
        </xsd:complexType>
    </xsd:schema>
</types>

<message name="getServerDate">
    <part name="none" type="xsd:int"/>
</message>

<message name="getServerDateResponse">
    <part name="value" type="typens:MyResults"/>
</message>

<portType name="CspPorts">
    <operation name="getServerDate">
        <input  message="getServerDate"/>
        <output message="getServerDateResponse"/>
    </operation>
</portType>

<binding name="MyBinding"  type="typens:CspPorts">
    <soap:binding style="rpc"
        transport="http://schemas.xmlsoap.org/soap/http" />
      <operation name="getServerDate">
          <soap:operation
             soapAction="http://www.votresite.com/fichier.wsdl"/>
        <input>
            <soap:body use="literal"/>
        </input>
        <output>
            <soap:body use="literal"/>
        </output>
    </operation>
</binding>

<service name="MyWebService">
    <documentation>Mon Service web</documentation>
        <port name="CspPorts" binding="typens:MyBinding">
      <soap:address location="http://votresite.com/server.php"/>
    </port>
  </service>

</definitions>

La classe

Cette classe, qui est très simpliste, va donc gérer notre service web, elle ne dispose que d'une unique méthode, getServerDate(), renvoyant la date courante du serveur.

<?php
class myWebService {

    // Méthode renvoyant une date standardisée
    function getServerDate() {
        return array('date' => date('Y-m-d\TH:i:s O'));
    }
}
?>

Mise en place du service web

Pour mettre en place notre serveur SOAP , nous allons donc tenter d'inctancier la classe soapServer en lui passant notre fichier WSDL en paramètre, si cela s'avère impossible nous gérerons une exception grâce à la classe soapFault. Nous definirons également notre classe comme gestionnaire du service web, grâce à la méthode soapServer :: setClass.
Si la méthode POST à été utilisée pour appeller cette page, on supposera qu'une requète SOAP a été envoyée et nous demanderons à notre serveur de la gérer grâce à la méthode soapServer :: handle, sinon nous afficherons la liste des fonctions du serveur grâce à la méthode soapServer :: getFunctions.

<?php

// La classe qui va gérer les requètes SOAP
class myWebService {

    // Méthode renvoyant une date standardisée
    function getServerDate() {
        return array('date' => date('Y-m-d\TH:i:s O'));
    }
}

// On tente d'instancier la classe soapServer
// Si cela s'avère impossible, on lève une exception
try {
    $server = new SoapServer('fichier.wsdl',  array('trace' => 1, 'soap_version' => SOAP_1_1));
    // On définit la classe qui va gérer les requètes SOAP
    $server -> setclass('myWebService');
} catch (Exception $e) {
    echo $e;
}

// La méthode POST a été utilisée pour appeller cette page.
// On suppose donc qu'une requète a été envoyée, on la gère
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    $server -> handle();
}
// sinon, on affiche une liste des méthodes que peut gérer ce serveur
else {
    echo '<strong>This SOAP server can handle following functions : </strong>';
    echo '<ul>';
    foreach($server -> getFunctions() as $func) {
        echo '<li>' , $func , '</li>';
    }
    echo '</ul>';
}
?>

Interroger notre service web (Client)

Le code PHP

Comme vous allez le constater, l'interrogation de notre service web s'avère extrémement simple grâce à la classe soapClient :

<?php
// Nouveau Client SOAP
try {
    // Nouvelle instance de la classe soapClient
    $client = new SoapClient('http://votresite.com/fichier.wsdl', array('trace' => 1, 'soap_version'  => SOAP_1_1));
    // appel de la méthode getServerDate du service web
    $O =  $client -> __call('getServerDate', array());
    // Affichage du résultat
    echo $O->date ;
} catch (SoapFault $fault) {
    echo $fault;
}

?>

Résultats

Voici ce que vous devriez voir apparaître à l'ecran, le serveur SOAP nous a donc renvoyé la date :

2009-01-10T00:24:52 +0100

Notes

* Si vous ne voulez pas utiliser les exceptions pour gérer les erreurs, l'extension SOAP met à votre disposition la fonction is_soap_fault().

* PHP met les fichiers WSDL en cache, si vous êtes amenés à modifier ces derniers, il est nécessaire de désactiver ce cache pour que vos modifications soient prises en compte. Les fichiers sont mis en cache pour une durée de 24 heures par défaut et ce, dans le répertoire /tmp. Trois directives (soap.wsdl_cache_enabled, soap.wsdl_cache_dir et soap.wsdl_cache_ttl) sont modifiables via le php.ini ou la fonction ini_set() et permettent de gérer ça, voici, par exemple, comment désactiver le cache :

<?php
// Désactivation du cache WSDL
ini_set('soap.wsdl_cache_enabled', 0);

// suite de votre script
?>

Conclusion

Encore une fois, PHP 5 nous apporte ici une nouvelle fonctionnailté très intéressante, qui simplifie grandement les choses en matière d'interrogation ou de création de service web. Le même résultat aurait demandé quelques centaines de lignes de code en PHP 4. Cette extension reste néanmoins expérimentale, son comportement pouvant changer à tout moment , et ce sans préavis, il convient de rester prudent.
Bon service web à toutes et à tous :)

Liens utiles

Fabrice Lezoray < fabrice AT scriptsphp.org >.

Trackback

Il n'y a pas de trackback recensé pour cet article.

Faire un trackback sur cet article http://classes.scriptsphp.org/Trackbackserver.Construire-un-service-web-en-php-5, récupérer les trackback sur cet article