PHP n'est malheureusement pas une plateforme cible privilégiée pour créer des web services. Pourtant, PHP5 dispose d'une bonne interface SOAP qui rend la création de client vraiment triviale ... ça reste un peu plus sportif pour un serveur, mais on y reviendra.

Mon premier exemple ici sera un simple "Echo", c'est-à-dire un web service qui renverra simplement la chaîne qu'on lui a fournit, le fournisseur étant ici un application server webMethods.

Un exemple très simple car les besoins de développements spécifiques sont généralement pour faire des clients. Et comme la partie serveur est plus complexe, je voulais commencer par faire peur.

Je ne vais pas entrer dans les détails, vu que ce n'est pas le propos de ce billet et c'est une chose relativement simple depuis la version 7.1. Il faut suivre la procédure suivante :

• Creer le service dans webMethods avec
  • chaîne Msg comme entrée
  • chaîne Response comme sortie
  • un flow qui ne contient qu'une map de Msg vers Response.
• que l'on associe avec un web service, grâce à l'assistant New / WebService Descriptor :
  • Provider
  • From existing IS service
  • on le nome "TestEchoWS" et il est stocké dans un package STPrivateLF
  • on choisi le service qu'on a créé précédemment
  • Soap 1.1
  • RPC literal

Et voila, c'est fini.

Le code pour un client est vraiment très simple et se résume à :

• Créer un objet SoapClient avec en paramètre l'URL vers la définition WSDL
• De cet objet, utiliser la méthode qui a le nom du service que l'on souhaite appeler.
• En retour, on obtient un objet qui contient la réponse du service.

Et ca donne :

#!/usr/bin/php
<?php
/* Test d'appel a un WEBService */
$wsdl = 'http://monserveur.chez.moi/ws/STPrivateLF.TestWS:TstEchoWS?WSDL';
$options = array('cache_wsdl' => WSDL_CACHE_NONE);

try {
	$soapclt = new SoapClient($wsdl, $options);
	$res = $soapclt->Echo( 'coucou' );
	echo "Ok !n";
	var_dump($res);
} catch (SoapFault $fault) {
	trigger_error("SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR);
}
?>

Note : le tableau $options ne contient ici que la directive qui supprime le cache du fichier WSDL. Si on peut (doit) le faire pendant le développement, on gagnera grandement à le laisser activé pour une utilisation réelle.

On le lance et on obtient :

laurent@Nunux:~/projets/b2b/testWS$ ./tstEcho 
Ok !
string(27) "Your message was : 'coucou'"

Simple non ?

Une des raison pour laquelle JAVA et .net sont souvent associés aux web services, c'est qu'ils sont fortement typés et donc qu'ils peuvent générer facilement des définitions WSDL. Avec PHP, faiblement typés, il n'y a pas à ce jour cette possibilité de génération automatique (Soyons clairs, on peut très bien se  passer du WSDL, mais c'est quant même tellement plus pratique ... ).

Comme ce problème n'est pas nouveau, quelques solutions sont apparues sur la toile ... plus ou moins abouties. Je me suis arrêté sur wsdl-writer qui fait du bon boulo sans être trop complexe. Heureusement d'ailleurs qu'il fonctionne bien car son créateur a abandonné son développement, repris par une certaine Katy ... dont le site n'est même plus en ligne (MàJ 2013 : son site est de retour ...). Mais, comme je l'ai dit, il a l'avantage de fonctionner.
J'ai pu le retrouver sur le site de placeoweb que je remercie au passage sinon j'aurai sans doute laissé tomber.

C'est simple, il suffit d'extraire l'archive et de modifier le fichier bin/wsdl pour qu'il trouve le répertoire contenant ses classes.

bin/wsdl est un script qui se lance du shell, qui lit les commentaires de la définitions d'une classes pour générer le WSDL ... comme on le verra dans les exemples ci-dessous.

Commençons par un simple web service qui ne fait que renvoyer un message : le classique du classique donc.

Ce fichier contient TOUTE la partie serveur, c'est-à-dire à la fois la classe qui implémente le webservice et le code générique d'interfaçage nécessaire à PHP.
TOUTE : car nous sommes ici dans un exemple. Dans un projet réel un peu complexe, il sera sans doute plus judicieux de les mettre dans des fichiers différents, surtout pour faciliter le travail de wdsl-writer ... mais on voit que ça fonctionne aussi avec un seul fichier.

<?php
/* classe d'implementation du web service */
class hello {

    /**
     * Hello World Method
     *
     * @return string On dit bonjour
     */
    public function helloWorld() {
		return "Cool, ca marche";
	}
}

/* partie serveur */
$soap = new SoapServer(
	'hello.wsdl',
	array('uri' => 'http://127.0.0.1/~laurent')
);
$soap->setClass('hello');
$soap->handle();
?>

Pour la classe d'implémentation :

• La première chose importante à noter est que le fichier doit porter le nom de la classe qui implémente le webservice.
• Ensuite, comme dit plus haut, PHP n'étant pas fortement typé, on doit spécifier la signature des services à exporter dans un commentaire qui se trouve immédiatement avant la définition de la méthode correspondante.
  • /** - indique que l'on démarre une definition
  • * @return string On dit bonjour - le service renvoie (return) une chaîne (string) le reste n'étant que des commentaires.
    ATTENTION : Il semblerait que wsdl-writer ait parfois des problèmes si le commentaire est absent.

Pour la partie serveur :

• On commence par créer un objet SoapServer en passant en argument le fichier wsdl (qui n'existe pas encore) et l'URI du serveur web.
• $soap->setClass('hello'); associe la classe au SoapServer.
  Une méthode alternative aurait été d'ajouter la fonction du webservice par un SoapServer::addFunction(). Cependant, il est plus pratique et plus propre de les grouper dans une classe, ainsi la maintenance sera simplifiée, tout se trouvant au même endroit.
• enfin la méthode handle() appel la méthode correspondant au webservice.

Très simple :

.../wsdl_writer/bin/wsdl hello.php http://127.0.0.1/~laurent/ hello.wsdl endpoint.php

avec

• hello.php - notre fichier définissant la classe
• http://127.0.0.1/~laurent/ - l'URI du web service
• hello.wsdl - le fichier wsdl à générer - optionnel
• endpoint.php - un nom du fichier qui contient le dispatcher et qui sera ajouté à l'URI (en clair, ici les webservices seront appelés par l'URL  http://127.0.0.1/~laurent/endpoint.php) - optionnel

Comme indiqué, les fichiers wsdl et endpoint sont optionnels : S'ils sont absents, <nom_classe>.wsdl et <nom_classe>.php sont utilisés.

Enfin, on place hello.php et hello.wsdl dans le répertoire du site web correspondant à l'URI. Ici ça sera public_html de mon compte.

On est dans un domaine connu :

#!/usr/bin/php
<?php
/* Test d'appel a un WEBService */
$wsdl = 'http://127.0.0.1/~laurent/hello.wsdl';
$options = array('trace'=>true, 'cache_wsdl' => WSDL_CACHE_NONE );

try {
	$soapclt = new SoapClient($wsdl, $options);
	$res = $soapclt->HelloWorld();
	echo "Ok !n";
	var_dump($res);
} catch (SoapFault $fault) {
	trigger_error("SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR);
}
?>

laurent@chose:~/projets/tstPHPWS/HelloWorld$ ./tstHello 
Ok !
string(15) "Cool, ca marche"
laurent@chose:~/projets/tstPHPWS/HelloWorld$ 

Vous trouverez les fichiers correspondant dans cette archive.

Exactement le même webservice que dans l'exemple 1 ... sauf qu'ici, le fournisseur est écrit en PHP.

Pour une raison qui m'échappe, je n'ai pu mettre ce coup-ci à la fois la classe et le dispatcher dans le même fichier.

La définition de la classe gagne donc un paramètre @param string $s comme suit :

class WSEcho {
    /**
     * Echo method
     *
     * @param string $s First integer
     * @return string Result of addition
     */
    public function allo($s)
    {
        return "Votre chaine etait '$s'";
    }
}

Et tous les fichiers correspondants sont disponibles dans cette archive.

Il est possible de passer en argument ou de retourner un objet complexe, autrement dit ... une classe. Dans cette exemple, nos webservices, renvoient une date et une heure sous la forme d'une structure.

Dans notre fichier include, on trouve d'abord la définition de notre classe.

class DateHeure {
	/** @var int date au format AAAAMMJJ */
	public $date;

	/** @var int heure au format HHMM*/
	public $heure;

	/** @var int timestamp, l'instant a convertir
	 * @access private
	 */
	private $ts;	// Normalement, celui-ci ne devrait pas etre exporte car privavee

	/**
	 * Constructeur de DateHeure
	 *
	 * @var int ats timestamp a convertir, si NULL, c'est on prend l'heure actuelle
	 */
	public function __construct($ats = NULL){
		$this->ts = $ats ? $ats : time();

		$this->date = Date('Ymd', $this->ts);
		$this->heure = Date('His', $this->ts);
	}
}

On remarquera au passage que la variable privée ne sera pas exportée dans le fichier WSDL.

Suit la classe correspondant aux web services.

class Horloge {
	/**
	 * Classe de test qui renvoie l'heure et la date
	 *
	 * @return DateHeure bla bla
	 */
	public function QuelleHeure(){
		return new DateHeure();
	}


	/**
	 * Classe de test qui renvoie l'heure et la date d'un timestamp
	 *
	 * @param int $ts bla bla
	 * @return DateHeure  bla bla
	 */
	public function QuelleHeureEtaitIl( $ts ){
		return new DateHeure( $ts );
	}
}

Il y en a 2, car en PHP, il est possible d'avoir un argument avec une valeur par défaut ... possibilité que je n'ai pas retrouvée au niveau du WSDL (n'hésitez pas à m'envoyer un message si vous savez comment faire ). Évidemment, cela implique aussi que les 2 webservices aient un nom différent.

Et voici une archive des codes correspondants.

Avant de déployer un web service, il faut bien évidemment prendre en compte l'aspect sécurité. Et comme ça peut se faire classiquement au niveau d'http, on est en terrain connu.  

Nous allons reprendre l'exemple précédent et simplement ajouter une authentification.  

On ne va pas faire de fioritures, on reste dans le classique : 

laurent@chose:~$ cd ~/public_html
laurent@chose:~/public_html$ htpasswd -c .htpasswd test
New password: 
Re-type new password: 
Adding password for user test
laurent@chose:~/public_html$

Et on crée un fichier .htaccess comme suit :

AuthType Basic
AuthName "Test"
AuthUserFile /home/laurent/public_html/.htpasswd
Require user test

Là non plus aucune difficulté : il n'y a juste qu'à rajouter le login et le mot de passe dans les options de SoapClient comme suit :

$options = array('trace'=>true, "exceptions" => true, 'cache_wsdl' => WSDL_CACHE_NONE, 'login' => 'test', 'password' => 'MonPassWD');

laurent@chose:~/projets/b2b/tstPHPWS/Class$ ./tstHorloge 
Ok !
object(stdClass)#2 (2) {
  ["date"]=>
  int(20110406)
  ["heure"]=>
  int(4925)
}
Ok !
object(stdClass)#3 (2) {
  ["date"]=>
  int(20110402)
  ["heure"]=>
  int(132925)
}

wsdl-writer est à la fois très chatouilleux au niveau de la syntaxe des fichiers PHP et en même temps très timide : s'il ne comprend pas quelque chose, c'est simple, il l'ignore ... ce qui ne nous rend pas forcement la tâche facile.

Dans mon cas, il semble qu'il n'apprécie que moyennement d'avoir des définitions de variable, d'argument ou de retour qui ne contiennent pas de commentaire. 

Cette erreur indique que le parser XML de PHP ne valide pas la réponse qu'il reçoit ... ce qui n'est pas forcement dû au web service lui-même comme nous allons le voir. Face à cette erreur, il faut :

1. Vérifier que le fichier WSDL contient bien les informations qu'on attend : Typiquement, il m'est arrivé de modifier la signature d'une fonction sans que ce soit répercuté dans le WSDL reçu par le client ... et si les 2 ne correspondent pas, SoapServer ne renvoie rien ! (y'a peut-être une exception levée par handle() mais j'avoue humblement ne pas avoir vérifié).
2. Supprimer les exceptions de SoapClient, activer les traces et afficher le contenu de la requête et de la réponse, comme dans le code suivant :

   $options = array('trace'=>true, "exceptions" => false, 'cache_wsdl' => WSDL_CACHE_NONE );
   
   try {
   	$soapclt = new SoapClient($wsdl, $options);
   	$res = $soapclt->QuelleHeure();
   	echo "Ok !n";
   	var_dump($res);
   print "<pre>n";
   print "Request :n"".$soapclt->__getLastRequest() .""n";
   print "Response:n"".$soapclt->__getLastResponse().""n";
   print "</pre>n";
    } catch (SoapFault $fault) { 	trigger_error("SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR); }

   On vérifie que le XML des 2 est bien valide.
3. Si c'est le cas, vérifier ... qu'il n'y ait pas d'espace ou de retour à la ligne devant la balise d'ouverture d'XML et après celle de fermeture. En effet, notre XML est pourtant bien valide, mais le parser de PHP n'aime pas du tout.
   Parfois, on n'arrive pas à trouver d'où est provient le problème ... alors il faut supprimer TOUS les retours chariot qui pourrait se trouver après la balise de fermeture de PHP de chacun de nos includes (J'ai mis du temps à la trouver celle la !!!!!). Heu, ça ressemble quant même furieusement à un bogue de PHP ce truc la, mais bon ...