15.2. Zend_XmlRpc_Client
Précédent | Chapitre 15. Zend_XmlRpc | Suivant

## 15.2. Zend_XmlRpc_Client

### 15.2.1. Introduction

L'utilisation de `Zend_XmlRpc_Client` est très similaire à celle de l'objet `SoapClient` (extention SOAP). Vous pouvez simplement appeler les preocédures du service XML-RPC comme méthodes de `Zend_XmlRpc_Client`. Spécifiez l'adresse complète du service dans le constructeur de `Zend_XmlRpc_Client`.

Exemple 15.1. Une requête XML-RPC de base

    <?php
    /**
     * Connexion au serveur framework.zend.com, et affichage d'un tableau
     * décrivant les méthodes disponibles.
     */
    require_once 'Zend/XmlRpc/Client.php';

    $server = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');

    print_r( $server->system->listMethods() );

    ?>

| Note
`Zend_XmlRpc_Client` tente de rendre les méthodes distantes le plus ressemblantes possible aux méthode natives. Si une méthode contient des espaces de noms, comme `system.listMethods()` ci-dessus, l'appel est fait en utilisant une chaîne d'objet dans PHP : `$server->system->listMethods()`.

### 15.2.2. Utiliser des paramètres

Des procédures du service XML-RPC requiert des paramètres, les paramètres nécessaires sont passés comme des paramètres de la méthode `Zend_XmlRpc_Client`. Les paramètres d'une procédure XML-RPC doit être spécifique à un type XML-RPC. Les paramètres peuvent être passés par 2 façons : en tant que natifs PHP ou en tant qu'objet `Zend_XmlRpc_Value` représentants des types XML-RPC.

#### 15.2.2.1. Passer des variables natives PHP en paramètre

Les paramètres passés comme des variables PHP natives, c'est à dire une chaîne, un flottan, un bouléen, un tableau ou un objet. Dans ce cas, chaque natif PHP, sera auto-déclaré et convertit dans un des types XML-RPC conformément à cette table :

Tableau 15.1. Convertion des valeurs PHP natives en types XML-RPC

Type natif PHP | XML-RPC type
--- | ---
entier | int
double | double
boolean | boolean
string | string
tableau | tableau
tableau associatif | structure
objet | tableau

    ...
    /** 2 paramètres sont passés dans cette procédure
     *  Le premier paramètre est une chaîne qui va être convertie automatiquement dans un type XML-RPC
     *  Le second paramètres et un tableau associatif qui va être converti dans une structure XML-RPC
     */

    $p1 = 'parameter 1';
    $p2 = array('name' => 'Joe', 'age' => 30);

    $service->serviceProcedure($p1, $p2);
    ...

#### 15.2.2.2. Passer des objets `Zend_XmlRpc_Value` comme paramètres

Les paramètres passés en tant qu'objet `Zend_XmlRpc_Value`. Vous pouvez créer une des instances `Zend_XmlRpc_Value` pour spécifier le type XML-RPC exact de vos paramètres. Les principales raisons pour spécifier explicitement les types XML-RPC peuvent être :

- Lorsque vous voulez être certain que le type correct de paramètre est passé à la procédure (i.e la procédure requiert un entier et vous souhaitez recevoir le paramètres comme une chaîne issue de $_GET).
- Lorsque la procédure requiert un type base64 ou dateTime.iso8601 (ce qui n'existe pas en tant que type PHP natif).
- Lorsque l'auto convetion peut échouer (i.e vous voulez passer une structure XML-RPC vide comme paramètre, une structure vide est représentée comme un tableau PHP vide, mais si vous lui donnez un tableau vide comme paramètre, il sera automatiquement converti en un tableau XMl-RPC, vu que ce n'est pas un tableau associatif).

Il y a 2 façons de créer un objet `Zend_XmlRpc_Value` : la façon explicite (appel de son constructeur) ou l'utilisation de la fonction statique `Zend_XmlRpc_Value::getXmlRpcValue()` avec la constante de type XML-RPC voulue.

Tableau 15.2. L'objet Zend_XmlRpc_Value représentant les types XML-RPC

type XML-RPC | Constancte `Zend_XmlRpc_Value` correspondante | objet `Zend_XmlRpc_Value`
--- | --- | ---
int | `Zend_XmlRpc_Value::XMLRPC_TYPE_INTEGER` | `Zend_XmlRpc_Value_Integer`
double | `Zend_XmlRpc_Value::XMLRPC_TYPE_DOUBLE` | `Zend_XmlRpc_Value_Double`
boolean | `Zend_XmlRpc_Value::XMLRPC_TYPE_BOOLEAN` | `Zend_XmlRpc_Value_Boolean`
string | `Zend_XmlRpc_Value::XMLRPC_TYPE_STRING` | `Zend_XmlRpc_Value_String`
base64 | `Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64` | `Zend_XmlRpc_Value_Base64`
dateTime.iso8601 | `Zend_XmlRpc_Value::XMLRPC_TYPE_DATETIME` | `Zend_XmlRpc_Value_DateTime`
array | `Zend_XmlRpc_Value::XMLRPC_TYPE_ARRAY` | `Zend_XmlRpc_Value_Array`
struct | `Zend_XmlRpc_Value::XMLRPC_TYPE_STRUCT` | `Zend_XmlRpc_Value_Struct`

    ...
    /** 2 paramètres sont passés dans cette procédure
     *  Le premier paramètre est un type XML-RPC base64, créé en utilisant la fonction statique Zend_XmlRpc_Value::getXmlRpcValue().
     *  Le second paramètre est une structure XML-RPC créée explicitement
     */

    $p1 = ZXmlRpcValue::getXmlRpcValue('chaîne encodée', Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64);
    $p2 = new Zend_XmlRpc_Value_Struct(array('name' => 'Joe', 'age' => 30));

    $service->serviceProcedure($p1, $p2);
    ...

| Note
La valeur du paramètre est quand même donnée dans une variable PHP, mais sera convertie dans le type spécifié, en utilisant les techniques de convertion de PHP. (i.e si une chaine est donnée en tant que valeur à l'objet `Zend_XmlRpc_Value_Integer`, elle sera convertie en utilisant `(int)$value`).

#### 15.2.2.3. Parser une chaîne XML dans un paramètre XML-RPC

Cette méthode de passage de paramètre est utilisée dans le paquet `Zend_XmlRpc` et n'est pas recommendée.

Si vous avez quand même besoin de cette méthode, vous devriez utiliser la fonction statique `Zend_XmlRpc_Value::getXmlRpcValue()` pour parser une chaîne XML dans un objet `Zend_XmlRpc_Value` qui représent le type XML-RPC correspondant. La fonction `Zend_XmlRpc_Value::getXmlRpcValue()` devrait recevoir 2 paramètres : la chaîne XML et la constante `Zend_XmlRpc_Value::XML_STRING`.

### 15.2.3. Typage objet implicite des paramètres (Type hinting)

La principale différence entre les services web XML-RPC et SOAP est le fichier WSDL. Le protocole SOAP has habituellement un fichier WSDL qui décrit l'interface du service web, conformément à cette interface, les clients SOAP savent quel est le type nécessaire du paramètre qui doit être envoyé au serveur, et quelle est sa valeur de retour. Sans le fichier WSDL, l'utilisateur risque d'avoir un problème pour connaitre ces types.

La façon dont cela a été résolu dans le protocole XML-RPC est avec une procédure spéciale du service appelée `system.methodSignature`. Cette procédure prend un nom de procédure en paramètre, et retourne sa signature, la signature est le type de paramètre nécéssaire, et le type de la valeur de retour de cette procédure.

| Note
Tout les serveurs XML-PRC ne supportenant pas la procédure spéciale `system.methodSignature`, les serveurs qui ne le supporte pas ne peuvent pas supporter le type hinting.

`Zend_XmlRpc_Client` implémente une sorte de fichier 'WSDL' pour un serveur XML-RPC en utilisant la procédure `system.methodSignature`. Si besoin est, `Zend_XmlRpc_Client` va demander une liste de toutes les procédures d'un serveur XML-RPC, toutes leurs signatures, et va conserver ses données dans un fichier XML (similaire au fichier WSDL de SOAP). Lorsque vous utiliser de nouveau ce serveur XMl-RPC, l'utilisateur peut fournir ce fichier XML et `Zend_XmlRpc_Client` va typer implicitement les paramètres pour la procédure nécessaire, conformément à leurs signatures.

Le fichier des signatures des procédure XML est créé en appelant la fonction `Zend_XmlRpc_Client::__getMethodsXml()` (la fonction retourne une chaîne XML contenant toutes les données des signatures) Pour définir un fichier XML de signature existant, l'utilisateur peut passer les données XML dans un paramètre du constructeur `Zend_XmlRpc_Client` ou en appelant la fonction `Zend_XmlRpc_Client::__setMethodsXml()`.

Exemple 15.2. Appeler un service XML-RPC avec le typage objet implicite (Type hinting)

    <?php
    /**
     * Connexion à un serveur XML-RPC, et enregistrement du fichier de ses signatures (l'équivalent du fichier WSDL de SOAP)
     */
    require_once 'Zend/XmlRpc/Client.php';

    $service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc');

    file_put_contents('/tmp/xmlrpc-signatures/example.xml', $service->__getMethodsXml());

    /*
      L'objet $service contient toutes les signatures du server XML-RPC,
      lorsque serviceProcedure est appelé, son paramètre ($param) est converti
      dans le type nécessaire, conformément à la signature de la procédure.
    */
    $service->serviceProcedure($param);
    ?>

    <?php
    /**
     * Connexion à un serveur XML-RPC, en utilisant un fichier de signature existant,
     * vérification que le type des paramètres passés à la procédure sont bien du type nécessaire.
     */
    require_once 'Zend/XmlRpc/Client.php';

    $signature_file_xml = file_get_contents('/tmp/xmlrpc-signatures/example.xml');
    $service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc', 'namespace', $signature_file_xml);

    /*
      L'objet $service contient toutes les signatures du server XML-RPC,
      lorsque serviceProcedure est appelé, son paramètre ($param) est converti
      dans le type nécessaire, conformément à la signature de la procédure.
    */
    $service->serviceProcedure($param);
    ?>

### 15.2.4. Récupérer la réponse

La préocédure XMl-RPC retourne une valeur dans un type XMl-RPC. La méthode `Zend_XmlRpc_Client` qui apelle cette procédure XMl-RPC retourne un type natif PHP, qui a été converti à partir du type XML-RPC retourné.

Vous pouvez utiliser la fonction `Zend_XmlRpc_Client::__getResponse()` pour récupérer la valeur de retour de la procédure voulue. La fonction `__getResponse()` reçoit un paramètre qui indique le type de la valeur de retour. Les options sont :

- `Zend_XmlRpc_Client::RESPONSE_PHP_NATIVE` - Retourne la valeur de retour de la procédure en tant que type natif PHP (convertion d'un type XML-RPC dans un type PHP).
- `Zend_XmlRpc_Client::RESPONSE_XML_STRING` - Retourne la représentation sous forme de chaîne XML de la réponse XMl-RPC.
- `Zend_XmlRpc_Client::RESPONSE_ZXMLRPC_OBJECT` - Retourne un objet `Zend_XmlRpc_Value` qui représente le type XML-RPC retourné.

    ...
    $service->serviceProcedure();

    $response = $service->__getResponse();
    // $response est la variable PHP convertie depuis la valeur de retour XML-RPC

    $response = $service->__getResponse(ZXmlRpcClient::RESPONSE_XML_STRING);
    // $response est une chaîne XML représentant la valeur de retour de la procédure

    $response = $service->__getResponse(ZXmlRpcClient::RESPONSE_ZXMLRPC_OBJECT);
    // $response est une instance Zend_XmlRpc_Value représentant le type XML-RPC de la valeur retournée
    ...

Précédent | Niveau supérieur | Suivant
Chapitre 15. Zend_XmlRpc | Sommaire | Annexe A. Convention de codage PHP du Framework Zend