| blob | e1ed2a54af5bd86545787931058231962b05574b |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- EN-Revision: 20794 -->
3 <!-- Reviewed: no -->
4 <sect1 id="zend.xmlrpc.client">
5 <title>Zend_XmlRpc_Client</title>
7 <sect2 id="zend.xmlrpc.client.introduction">
8 <title>Introduction</title>
10 <para>
11 Zend Framework possède la capacité de consommer des services distants XML-RPC, via
12 la classe <classname>Zend_XmlRpc_Client</classname>. Ses caractéristiques principales
13 sont la conversion automatique des types entre <acronym>PHP</acronym> et XML-RPC, un objet proxy de
14 serveur, et des possibilités d'introspection du serveur.
15 </para>
16 </sect2>
18 <sect2 id="zend.xmlrpc.client.method-calls">
19 <title>Appels de méthodes</title>
21 <para>
22 Le constructeur de <classname>Zend_XmlRpc_Client</classname> reçoit en premier
23 paramètre l'URL du serveur XML-RPC distant. L'instance retournée pourra alors être
24 utilisée pour appeler n'importe quelle méthode distante.
25 </para>
27 <para>
28 Pour appeler une méthode distante, utilisez la méthode <methodname>call()</methodname> de
29 votre instance. Le code suivant montre un exemple avec le serveur XML-RPC du site de
30 Zend Framework. Vous pouvez l'utiliser pour tester ou explorer les possibilités des
31 composants <classname>Zend_XmlRpc</classname>.
32 </para>
34 <example id="zend.xmlrpc.client.method-calls.example-1">
35 <title>XML-RPC appel de méthode</title>
37 <programlisting language="php"><![CDATA[
38 $client = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');
40 echo $client->call('test.sayHello');
42 // hello
43 ]]></programlisting>
44 </example>
46 <para>
47 Le type de la valeur XML-RPC retournée sera automatiquement casté en un type
48 compatible <acronym>PHP</acronym>. Dans l'exemple ci-dessus, une <code>string</code> <acronym>PHP</acronym> est retournée et
49 immédiatement utilisable.
50 </para>
52 <para>
53 Le premier paramètre de <methodname>call()</methodname> est le nom de la méthode distante à
54 appeler. Si celle-ci demande des paramètres, ceux-ci doivent alors être passés via le
55 deuxième paramètre de <methodname>call()</methodname>, sous forme de tableau <acronym>PHP</acronym>
56 (<code>array</code>) :
57 </para>
59 <example id="zend.xmlrpc.client.method-calls.example-2">
60 <title>XML-RPC appel de méthode avec des paramètres</title>
62 <programlisting language="php"><![CDATA[
63 $client = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');
65 $arg1 = 1.1;
66 $arg2 = 'foo';
68 $result = $client->call('test.sayHello', array($arg1, $arg2));
70 // $result est un type PHP natif
71 ]]></programlisting>
72 </example>
74 <para>
75 Le tableau de paramètres peut contenir des types <acronym>PHP</acronym> natifs, des objets
76 <classname>Zend_XmlRpc_Value</classname>, ou bien les deux à la fois.
77 </para>
79 <para>
80 La méthode <methodname>call()</methodname> convertira automatiquement la réponse XML-RPC et
81 retournera un type <acronym>PHP</acronym> natif valide. Un objet
82 <classname>Zend_XmlRpc_Response</classname> pour la valeur de retour sera de même
83 disponible, via un appel à <methodname>getLastResponse()</methodname>.
84 </para>
85 </sect2>
87 <sect2 id="zend.xmlrpc.value.parameters">
88 <title>Types et conversions</title>
90 <para>
91 Certaines méthodes distantes requièrent des paramètres. Ceux-ci sont donnés sous
92 forme de tableau <acronym>PHP</acronym> à <methodname>call()</methodname>. Chaque paramètre est supposé être un type
93 <acronym>PHP</acronym> natif qui sera alors lui-même converti, ou alors un objet représentant un type
94 XML-RPC (un objet parmi les <classname>Zend_XmlRpc_Value</classname>).
95 </para>
97 <sect3 id="zend.xmlrpc.value.parameters.php-native">
98 <title>Types PHP natifs comme paramètres</title>
100 <para>
101 Les paramètres passés à <methodname>call()</methodname> peuvent être d'un type <acronym>PHP</acronym> natif,
102 à savoir <code>string</code>, <code>integer</code>, <code>float</code>,
103 <code>boolean</code>, <code>array</code>, ou <code>object</code>. Dans ce cas,
104 chacun des types sera converti de manière automatique en son type compatible
105 XML-RPC, suivant la table suivante :
106 </para>
108 <table id="zend.xmlrpc.value.parameters.php-native.table-1">
109 <title>PHP et XML-RPC, conversions de types</title>
111 <tgroup cols="2">
112 <thead>
113 <row>
114 <entry>Type <acronym>PHP</acronym> natif</entry>
115 <entry>XML-RPC type</entry>
116 </row>
117 </thead>
119 <tbody>
120 <row>
121 <entry>integer</entry>
122 <entry>int</entry>
123 </row>
124 <row>
125 <entry>Zend_Crypt_Math_BigInteger</entry>
126 <entry>i8</entry>
127 </row>
128 <row>
129 <entry>double</entry>
130 <entry>double</entry>
131 </row>
132 <row>
133 <entry>boolean</entry>
134 <entry>boolean</entry>
135 </row>
136 <row>
137 <entry>string</entry>
138 <entry>string</entry>
139 </row>
140 <row>
141 <entry>null</entry>
142 <entry>nil</entry>
143 </row>
144 <row>
145 <entry>array</entry>
146 <entry>array</entry>
147 </row>
148 <row>
149 <entry>associative array</entry>
150 <entry>struct</entry>
151 </row>
152 <row>
153 <entry>object</entry>
154 <entry>array</entry>
155 </row>
156 <row>
157 <entry>Zend_Date</entry>
158 <entry>dateTime.iso8601</entry>
159 </row>
160 <row>
161 <entry>DateTime</entry>
162 <entry>dateTime.iso8601</entry>
163 </row>
164 </tbody>
165 </tgroup>
166 </table>
168 <note>
169 <title>Comment est casté un tableau vide ?</title>
171 <para>
172 Fournir un tableau vide à une méthode XML-RPC est problématique, car il
173 peut être représenté sous la forme soit d'un tableau, soit d'une structure
174 ("struct"). <classname>Zend_XmlRpc_Client</classname> détecte ce genre de
175 conditions et fait une requête vers la méthode
176 <code>system.methodSignature</code> du serveur pour déterminer le type XML-RPC
177 approprié vers le quel casté.
178 </para>
180 <para>
181 Cependant, ceci peut mener malgré tout à des soucis. Premièrement, les
182 serveurs qui ne supportent <code>system.methodSignature</code> vont retourner
183 une requête de type échec, et <classname>Zend_XmlRpc_Client</classname>
184 résultera en un cast de la valeur de type tableau XML-RPC ("array"). De plus,
185 ceci sous-entend que tout appel avec des arguments de type tableau entraîneront
186 un appel additionnel au serveur distant.
187 </para>
189 <para>
190 Pour désactiver entièrement la recherche, vous pouvez appeler la méthode
191 <methodname>setSkipSystemLookup()</methodname> avant de réaliser votre appel XML-RPC
192 :
193 </para>
195 <programlisting language="php"><![CDATA[
196 $client->setSkipSystemLookup(true);
197 $result = $client->call('foo.bar', array(array()));
198 ]]></programlisting>
199 </note>
200 </sect3>
202 <sect3 id="zend.xmlrpc.value.parameters.xmlrpc-value">
203 <title>Objets <classname>Zend_XmlRpc_Value</classname> en tant que
204 paramètres</title>
206 <para>
207 Les paramètres peuvent aussi être des objets
208 <classname>Zend_XmlRpc_Value</classname> qui spécifient alors exactement un type
209 XML-RPC. Les raisons principales d'utiliser un tel procédé sont : <itemizedlist>
210 <listitem>
211 <para>
212 Lorsque vous voulez être certain du type de paramètre (la méthode
213 attend un entier et vous le récupérez sous forme de chaîne de caractères
214 depuis une base de données).
215 </para>
216 </listitem>
218 <listitem>
219 <para>
220 Lorsque la méthode attend un type <code>base64</code> ou
221 <code>dateTime.iso8601</code> (ceux-ci n'existant pas nativement dans le
222 langage <acronym>PHP</acronym>).
223 </para>
224 </listitem>
226 <listitem>
227 <para>
228 Lorsque la conversion de types (cast) peut échouer (vous voulez
229 passer une valeur XML-RPC vide comme paramètre. Mais les valeurs vides
230 en <acronym>PHP</acronym> sont représentés sous forme de tableaux vides, or si vous passez
231 un tableau vide à votre méthode <code>call</code>, il va être converti
232 en un tableau XML-RPC, comme ce n'est pas un tableau associatif).
233 </para>
234 </listitem>
235 </itemizedlist>
236 </para>
238 <para>
239 Deux manières existent pour créer des objets
240 <classname>Zend_XmlRpc_Value</classname> : instanciez une sous-classe
241 <classname>Zend_XmlRpc_Value</classname> directement, ou utilisez une fabrique
242 ("factory method") telle que
243 <methodname>Zend_XmlRpc_Value::getXmlRpcValue()</methodname>.
244 </para>
246 <table id="zend.xmlrpc.value.parameters.xmlrpc-value.table-1">
247 <title>Objets <classname>Zend_XmlRpc_Value</classname> comme types
248 XML-RPC</title>
250 <tgroup cols="3">
251 <thead>
252 <row>
253 <entry>XML-RPC Type</entry>
254 <entry><classname>Zend_XmlRpc_Value</classname> Constante</entry>
255 <entry><classname>Zend_XmlRpc_Value</classname> Objet</entry>
256 </row>
257 </thead>
259 <tbody>
260 <row>
261 <entry>int</entry>
262 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_INTEGER</constant></entry>
263 <entry><classname>Zend_XmlRpc_Value_Integer</classname></entry>
264 </row>
266 <row>
267 <entry>i8</entry>
268 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_I8</constant></entry>
269 <entry><classname>Zend_XmlRpc_Value_BigInteger</classname></entry>
270 </row>
272 <row>
273 <entry>ex:i8</entry>
274 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_APACHEI8</constant></entry>
275 <entry><classname>Zend_XmlRpc_Value_BigInteger</classname></entry>
276 </row>
278 <row>
279 <entry>double</entry>
280 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_DOUBLE</constant></entry>
281 <entry><classname>Zend_XmlRpc_Value_Double</classname></entry>
282 </row>
284 <row>
285 <entry>boolean</entry>
286 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_BOOLEAN</constant></entry>
287 <entry><classname>Zend_XmlRpc_Value_Boolean</classname></entry>
288 </row>
290 <row>
291 <entry>string</entry>
292 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_STRING</constant></entry>
293 <entry><classname>Zend_XmlRpc_Value_String</classname></entry>
294 </row>
296 <row>
297 <entry>nil</entry>
298 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_NIL</constant></entry>
299 <entry><classname>Zend_XmlRpc_Value_Nil</classname></entry>
300 </row>
302 <row>
303 <entry>ex:nil</entry>
304 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_APACHENIL</constant></entry>
305 <entry><classname>Zend_XmlRpc_Value_Nil</classname></entry>
306 </row>
308 <row>
309 <entry>base64</entry>
310 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64</constant></entry>
311 <entry><classname>Zend_XmlRpc_Value_Base64</classname></entry>
312 </row>
314 <row>
315 <entry>dateTime.iso8601</entry>
316 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_DATETIME</constant></entry>
317 <entry><classname>Zend_XmlRpc_Value_DateTime</classname></entry>
318 </row>
320 <row>
321 <entry>array</entry>
322 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_ARRAY</constant></entry>
323 <entry><classname>Zend_XmlRpc_Value_Array</classname></entry>
324 </row>
326 <row>
327 <entry>struct</entry>
328 <entry><constant>Zend_XmlRpc_Value::XMLRPC_TYPE_STRUCT</constant></entry>
329 <entry><classname>Zend_XmlRpc_Value_Struct</classname></entry>
330 </row>
331 </tbody>
332 </tgroup>
333 </table>
335 <para>
336 <note>
337 <title>Conversion automatique</title>
339 <para>
340 Lorsque vous créez un objet <classname>Zend_XmlRpc_Value</classname>,
341 sa valeur est déterminée par un type <acronym>PHP</acronym>. Celui-ci va être converti vers le
342 type désiré en utilisant le cast <acronym>PHP</acronym>. Par exemple si une chaîne de
343 caractères est donnée comme valeur à un objet
344 <classname>Zend_XmlRpc_Value_Integer</classname>, elle sera alors convertie
345 suivant la règle <code>(int)$value</code>.
346 </para>
347 </note>
348 </para>
349 </sect3>
350 </sect2>
352 <sect2 id="zend.xmlrpc.client.requests-and-responses">
353 <title>Objet proxy du serveur</title>
355 <para>
356 Un autre moyen d'appeler des méthodes avec un client XML-RPC est d'utiliser le
357 proxy du serveur. C'est un objet <acronym>PHP</acronym> qui proxie un espace de nom XML-RPC, en
358 fonctionnant autant que possible comme les objets <acronym>PHP</acronym>.
359 </para>
361 <para>
362 Pour instancier un proxy serveur, appelez <methodname>getProxy()</methodname> de
363 <classname>Zend_XmlRpc_Client</classname>. Elle retourne un objet
364 <classname>Zend_XmlRpc_Client_ServerProxy</classname>. Tout appel de méthode sur l'objet
365 proxy sera proxié vers le serveur XML-RPC, et les paramètres seront utilisés comme pour
366 une méthode <acronym>PHP</acronym> banale.
367 </para>
369 <example id="zend.xmlrpc.client.requests-and-responses.example-1">
370 <title>Proxy espace de nom par défaut</title>
372 <programlisting language="php"><![CDATA[
373 $client = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');
375 $service = $client->getProxy();
376 // Proxy l'espace de nom par défaut
378 $hello = $service->test->sayHello(1, 2);
379 // test.Hello(1, 2) retourne "hello"
380 ]]></programlisting>
381 </example>
383 <para>
384 La méthode <methodname>getProxy()</methodname> reçoit un argument optionnel désignant l'espace
385 de nom à utiliser par le proxy. Par défaut, il s'agit de l'espace général, voici un
386 exemple utilisant un espace de nom <code>test</code> :
387 </para>
389 <example id="zend.xmlrpc.client.requests-and-responses.example-2">
390 <title>Proxy un espace de nom</title>
392 <programlisting language="php"><![CDATA[
393 $client = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');
395 $test = $client->getProxy('test');
396 // Proxy l'espace de nommage "test"
398 $hello = $test->sayHello(1, 2);
399 // test.Hello(1,2) retourne "hello"
400 ]]></programlisting>
401 </example>
403 <para>
404 Si le serveur distant supporte les espaces de noms imbriqués, alors le proxy les
405 supportera. Par exemple, si le serveur dans l'exemple ci-dessus acceptait les espaces de
406 noms imbriqués, alors sa méthode <code>test.foo.bar()</code> aurait pu être appelée via
407 <code>$test->foo->bar()</code>.
408 </para>
409 </sect2>
411 <sect2 id="zend.xmlrpc.client.error-handling">
412 <title>Gestion des erreurs</title>
414 <para>
415 Deux types d'erreurs peuvent être distingués : erreurs <acronym>HTTP</acronym>, ou erreurs XML-RPC.
416 L'objet <classname>Zend_XmlRpc_Client</classname> reconnaît ces erreurs et fournit les
417 moyens de les repérer et de les gérer.
418 </para>
420 <sect3 id="zend.xmlrpc.client.error-handling.http">
421 <title>Erreurs HTTP</title>
423 <para>
424 Si une erreur <acronym>HTTP</acronym> survient, par exemple le serveur renvoie un <code>404 Not
425 Found</code>, alors une <classname>Zend_XmlRpc_Client_HttpException</classname> sera
426 levée.
427 </para>
429 <example id="zend.xmlrpc.client.error-handling.http.example-1">
430 <title>Gérer les erreurs HTTP</title>
432 <programlisting language="php"><![CDATA[
433 $client = new Zend_XmlRpc_Client('http://foo/404');
435 try {
437 $client->call('bar', array($arg1, $arg2));
439 } catch (Zend_XmlRpc_Client_HttpException $e) {
441 // $e->getCode() retourne 404
442 // $e->getMessage() retourne "Not Found"
444 }
445 ]]></programlisting>
446 </example>
448 <para>
449 Quelque soit l'utilisation du client XML-RPC, une
450 <classname>Zend_XmlRpc_Client_HttpException</classname> sera systématiquement levée
451 lorsqu'une erreur <acronym>HTTP</acronym> de quelque type que ce soit est rencontrée.
452 </para>
453 </sect3>
455 <sect3 id="zend.xmlrpc.client.error-handling.faults">
456 <title>Erreurs XML-RPC (Faults)</title>
458 <para>
459 Une erreur XML-RPC peut être assimilée à une exception en <acronym>PHP</acronym>. C'est un type
460 spécial retourné par une des méthodes du client XML-RPC, et ce type contient un
461 message, et un code d'erreur. Les erreurs XML-RPC seront gérées différemment en
462 fonction du contexte d'utilisation de l'objet
463 <classname>Zend_XmlRpc_Client</classname>.
464 </para>
466 <para>
467 Lors de l'utilisation de la méthode <methodname>call()</methodname>, ou de l'objet proxy
468 serveur, une erreur XML-RPC aura pour effet de lancer une
469 <classname>Zend_XmlRpc_Client_FaultException</classname>. Le code et le message de
470 l'exception seront rendus dans leurs valeurs respectives de la réponse
471 XML-RPC.
472 </para>
474 <example id="zend.xmlrpc.client.error-handling.faults.example-1">
475 <title>Gérer les erreurs XML-RPC</title>
477 <programlisting language="php"><![CDATA[
478 $client = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');
480 try {
482 $client->call('badMethod');
484 } catch (Zend_XmlRpc_Client_FaultException $e) {
486 // $e->getCode() retourne 1
487 // $e->getMessage() retourne "Unknown method"
489 }
490 ]]></programlisting>
491 </example>
493 <para>
494 En utilisant <methodname>call()</methodname>, une exception
495 <classname>Zend_XmlRpc_Client_FaultException</classname> sera donc lancée si une
496 erreur survient. Un objet <classname>Zend_XmlRpc_Response</classname> contenant
497 l'erreur sera de même disponible via la méthode
498 <methodname>getLastResponse()</methodname>.
499 </para>
501 <para>
502 Lors de l'utilisation de la méthode <methodname>doRequest()</methodname>, aucune exception
503 ne sera levée si une erreur XML-RPC survient. Simplement, l'objet
504 <classname>Zend_XmlRpc_Response</classname> retourné contiendra l'erreur.
505 Vérifiez-en l'état avec <methodname>isFault()</methodname>.
506 </para>
507 </sect3>
508 </sect2>
510 <sect2 id="zend.xmlrpc.client.introspection">
511 <title>Introspection du serveur</title>
513 <para>
514 Certains serveurs XML-RPC supportent l'introspection de leurs méthodes au travers
515 de l'espace de noms <code>system.</code> <classname>Zend_XmlRpc_Client</classname>
516 fournit un support d'un tel procédé.
517 </para>
519 <para>
520 Une instance de <classname>Zend_XmlRpc_Client_ServerIntrospection</classname> sera
521 retournée si vous appelez la méthode <methodname>getIntrospector()</methodname> sur l'objet
522 <classname>Zend_XmlRpcClient</classname>.
523 </para>
524 </sect2>
526 <sect2 id="zend.xmlrpc.client.request-to-response">
527 <title>De la requête à la réponse</title>
529 <para>
530 Dans les faits, la méthode <methodname>call()</methodname> de
531 <classname>Zend_XmlRpc_Client</classname> fabrique un objet
532 <classname>Zend_XmlRpc_Request</classname> et l'envoie à une méthode
533 <methodname>doRequest()</methodname>, qui retourne un objet de réponse
534 <classname>Zend_XmlRpc_Response</classname>.
535 </para>
537 <para>La méthode <methodname>doRequest()</methodname> est disponible directement si besoin :</para>
539 <example id="zend.xmlrpc.client.request-to-response.example-1">
540 <title>Effectuer une requête et récupérer une réponse manuellement</title>
542 <programlisting language="php"><![CDATA[
543 $client = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');
545 $request = new Zend_XmlRpc_Request();
546 $request->setMethod('test.sayHello');
547 $request->setParams(array('foo', 'bar'));
549 $client->doRequest($request);
551 // $client->getLastRequest() retoure instanceof Zend_XmlRpc_Request
552 // $client->getLastResponse() retourne instanceof Zend_XmlRpc_Response
553 ]]></programlisting>
554 </example>
556 <para>
557 Lorsqu'une méthode XML-RPC est appelée, quel qu'en soit le moyen,
558 (<methodname>call()</methodname>, <methodname>doRequest()</methodname> ou proxy serveur), le dernier objet de
559 requête, et son homologue de réponse, seront toujours disponibles, au travers des appels
560 à <methodname>getLastRequest()</methodname> et <methodname>getLastResponse()</methodname>.
561 </para>
562 </sect2>
564 <sect2 id="zend.xmlrpc.client.http-client">
565 <title>Client HTTP et tests</title>
567 <para>
568 Dans tous les exemples utilisés sur cette page, nous ne parlons jamais du client
569 <acronym>HTTP</acronym>. Lorsque c'est nécessaire, une instance de <classname>Zend_Http_Client</classname>
570 sera créée par défaut et injectée dans <classname>Zend_XmlRpc_Client</classname> de
571 manière automatique.
572 </para>
574 <para>
575 L'objet client <acronym>HTTP</acronym> peut être récupéré à tout moment grâce à la méthode
576 <methodname>getHttpClient()</methodname>. <methodname>setHttpClient()</methodname> permet d'injecter un objet
577 <classname>Zend_Http_Client</classname>.
578 </para>
580 <para>
581 <methodname>setHttpClient()</methodname> est particulièrement utilisée pour les tests
582 unitaires. Lorsque combinée avec <classname>Zend_Http_Client_Adapter_Test</classname>,
583 les services Web peuvent être déguisés (émulés) pour les tests. Voyez les tests
584 unitaires de <classname>Zend_XmlRpc_Client</classname> pour des exemples
585 concrets.
586 </para>
587 </sect2>
588 </sect1>