Créer un WSDL facilement avec Zend Framework

Par le passé, je dois avouer avoir fait une tentative, une seule, pour créer à la main un fichier WSDL (Web Services Description Language) et je me suis promis que plus jamais je ne voulais revivre cette expérience. Certains outils existent pour automatiser cette pénible tâche et ceux que j'avais testé jusqu'à maintenant généraient un fichier .wsdl statique.

Pour expliquer simplement, un fichier WSDL comprend une structure XML qui définit les fonctions accessibles par le service, ses paramètres, les types et ce qui est retourné. Lorsque le comportement d'une des fonctions du service web change, on est obligé soit de modifier à la main la description, soit de regénérer le fichier WSDL et le redéposer sur le serveur.

Jusqu'à ce qu'on découvre l'objet Zend_Soap_AutoDiscover du Zend Framework. Sa force : être en mesure d'inspecter une classe au runtime et de générer à la volée le fichier WSDL correspondant.

Voici un petit tutoriel pour créer un premier service web, réduit à sa plus simple expression. J'offrirai le service de retourner le pourcentage de taxe associé au nom envoyé par le client.

1. Créer une classe qui offrira les services

Ici, ça peut être n'importe quelle classe, pas nécessairement une construite spécifiquement pour le service web. Une seule condition doit être respectée : suivre le format de documentation des docblocks car AutoDiscover se base sur commentaires pour construire la description WSDL.

Chaque fonction de la classe doit être précédée d'un docblock qui doit suivre la syntaxe suivante :

• @param type param_name
  
• @return type

Comme dans l'exemple ci-dessous :

// Ex: fichier "tax.class.php"

class Tax {

/**
* Return tax value
* @param string $type
* @return float
*/
public function getTaxValue($type = 'TPS'){
       // récupérer les taxes d'une quelconque façon,
       // par exemple d'une base de données

       // Taxe sur les Produits et Services
       if($type == 'TPS'){
           return 5.0;
       }
       // Taxe de Vente du Québec
       elseif ($type == 'TVQ'){
           return 7.5;
       }
       else {
           return 0;
       }

   }
}

Si vous rencontrez l'erreur "Fatal error: Uncaught SoapFault exception: [WSDL] SOAP-ERROR: Parsing WSDL: Missing <message>...", c'est probablement que votre docblock est mal structuré. Le commentaire doit absolument débuter par /**, avec deux astérisques (dans Eclipse, vous devriez voir une différence dans la coloration syntaxique).

2. Manipuler les requêtes du côté serveur

Comme c'est vous qui offrez un service, vous devrez préparer une page qui effectuera les manipulations des requêtes clients. Ce fichier aura deux utilités :

• retourner la description du WSDL lorsqu'un paramètre sera passé
• traiter la demande
  

// Ex: fichier "service.php"

require_once('Zend/Soap/AutoDiscover.php');
require_once('Zend/Soap/Server.php');
require_once('tax.class.php');

if(isset($_GET['wsdl'])){
   // inspecter la classe Tax et retourner la description
   $wsdl = new Zend_Soap_AutoDiscover();
   $wsdl->setClass('Tax');
   $wsdl->handle();
}
else{
   // traitement
   $server = new Zend_Soap_Server('http://localhost/WSDL/service.php?wsdl');
   $server->setClass('Tax');
   $server->handle();
}

Si l'erreur suivante se produit "Fatal error: Uncaught exception 'Zend_Soap_Server_Exception' with message 'SOAP extension is not loaded.'", c'est que l'objet Zend_Soap_Server utilise l'extension php_soap.so (ou .dll). Activez la dans php.ini.

Vous êtes maintenant prêts à fournir les taux de taxes.

3. Créer une requête en tant que client

Probablement qu'en temps normal, ce ne sera pas vous qui utiliserez votre service web mais mieux vaut le tester avant de l'offrir à vos clients. Ceux-ci pourront utiliser le langage de leur choix pour faire appel à votre service, mais nous, comme nous utilisons déjà le Zend Framework, nous allons nous servir d'un autre objet au nom évocateur de Zend_Soap_Client. Cet objet peut aussi être utilisé lorsque vous voudrez vous-même utiliser un service offert par un autre fournisseur. Rappelez-vous que du point de vue du client, il ne voit pas que c'est programmé en PHP, ils ne voient que la définition WSDL pour pouvoir communiquer avec lui.

Une fois la connection établie, le client peut appeler les fonctions comme un objet. Ici, il aura accès à la fonction getTaxValue.

// Ex: fichier "appel.php"

require_once('Zend/Soap/Client.php');

try {
   $client = new Zend_Soap_Client('http://localhost/WSDL/service.php?wsdl');

   echo 'La TPS est de : ' . $client->getTaxValue('TPS') . ' %';
   echo 'La TVQ est de : ' . $client->getTaxValue('TVQ') . ' %';
}
catch(Zend_Exception $e){
   echo $e->getMessage();
}

Ce qui devrait afficher ceci :
La TPS est de : 5 %
La TVQ est de : 7.5 %