| blob | fcd37fe81e8856645aa0884fbcb55e546ffa8eeb |
1 <sect1 id="zend.xmlrpc.client">
2 <title>Zend_XmlRpc_Client</title>
3 <sect2 id="zend.xmlrpc.client.introduction">
4 <title>Inleiding</title>
5 <para>
6 Het gebruik van de <code>Zend_XmlRpc_Client</code> komt erg overeen met het gebruik van <code>SoapClient</code> objecten (<ulink url="http://www.php.net/soap">SOAP web service extensie</ulink>).
7 Je kan gewoonweg de XML-RPC service procedures aanroepen als <code>Zend_XmlRpc_Client</code> methodes.
8 Specificeer het volledige adres van de service in de <code>Zend_XmlRpc_Client</code> constructor.
9 </para>
10 <example>
11 <title>Een basis XML-RPC verzoek</title>
12 <programlisting role="php"><![CDATA[<?php
13 /**
14 * Maak verbinding met de framework.zend.com server en krijg een array met de beschikbare methodes.
15 */
16 require_once 'Zend/XmlRpc/Client.php';
18 $server = new Zend_XmlRpc_Client('http://framework.zend.com/xmlrpc');
20 print_r( $server->system->listMethods() );
21 ?>]]>
22 </programlisting>
23 </example>
24 <para>
25 <note>
26 <para>De <code>Zend_XmlRpc_Client</code> probeert het op afstand aanroepen van methodes
27 zoveel mogelijk als PHP-eigen methodes te laten lijken. Als een remote methode namespaces bevat
28 zoals <code>system.listMethods()</code> hierboven, word de aanroep via "object chaining" gemaakt
29 in PHP: <code>$server->system->listMethods()</code>.</para>
30 </note>
31 </para>
32 </sect2>
33 <sect2 id="zend.xmlrpc.client.parameters">
34 <title>Parameters gebruiken</title>
35 <para>
36 Sommige XML-RPC service procedures vereisen parameters. De benodigde parameters worden als parameters voor
37 de <code>Zend_XmlRpc-Client</code> methode doorgegeven.
38 Parameters voor een XML-RPC procedure moeten van een bepaald XML-RPC type zijn.
39 Parameters kunnen op 2 manieren worden doorgegeven: als PHP-eigen variabelen of <code>Zend_XmlRpc_Value</code>
40 objecten die XML-RPC types voorstellen.
41 </para>
42 <sect3 id='zend.xmlrpc.client.parameters.php_native'>
43 <title>PHP-eigen variabelen als parameters doorgeven</title>
44 <para>
45 Parameters zoals een string, integer, float, boolean, array of object worden beschouwd als PHP-eigen variabelen
46 en zullen ook zo worden doorgegeven.
47 In dit geval zal elk PHP-eigen type automatisch worden herkend en geconverteerd in een van de overeenkomstige
48 XML-RPC types aan de hand van de volgende tabel:
49 </para>
50 <table>
51 <title>PHP en XML-RPC type omzetting</title>
52 <tgroup cols="2">
53 <thead>
54 <row>
55 <entry>PHP Native type</entry>
56 <entry>XML-RPC type</entry>
57 </row>
58 </thead>
59 <tbody>
60 <row>
61 <entry>integer</entry>
62 <entry>int</entry>
63 </row>
64 <row>
65 <entry>double</entry>
66 <entry>double</entry>
67 </row>
68 <row>
69 <entry>boolean</entry>
70 <entry>boolean</entry>
71 </row>
72 <row>
73 <entry>string</entry>
74 <entry>string</entry>
75 </row>
76 <row>
77 <entry>array</entry>
78 <entry>array</entry>
79 </row>
80 <row>
81 <entry>associative array</entry>
82 <entry>struct</entry>
83 </row>
84 <row>
85 <entry>object</entry>
86 <entry>array</entry>
87 </row>
88 </tbody>
89 </tgroup>
90 </table>
91 <programlisting role="php"><![CDATA[<?php
93 /** 2 parameters worden in deze procedure doorgegeven
94 * - De eerste parameter is een string die automatisch zal worden omgezet in een XML-RPC string type
95 * - De tweede parameter is een associatieve array die zal worden omgezet in een XML-RPC struct
96 */
98 $p1 = 'parameter 1';
99 $p2 = array('name' => 'Joe', 'age' => 30);
101 $service->serviceProcedure($p1, $p2);
103 ?>]]>
104 </programlisting>
105 </sect3>
106 <sect3 id='zend.xmlrpc.client.parameters.xmlrpc_value'>
107 <title><code>Zend_XmlRpc_Value</code> objecten als parameters doorgeven</title>
108 <para>
109 Je kan één van de volgende <code>Zend_XmlRpc_Value</code> instanties aanmaken om het preciese XML-RPC type
110 van je parameters aan te geven.
111 De hoofdredenen om expliciet het type van de doorgegeven parameters aan te duiden zijn de volgende:
112 <itemizedlist>
113 <listitem>
114 <para>Wanneer je er zeker van wil zijn dat het juiste parameter type aan de procedure wordt doorgegevn (b.v.: de procedure eist een integer en het is mogelijk dat de parameter via de $_GET array als een string krijgt)</para>
115 </listitem>
116 <listitem>
117 <para>Indien de procedure een base64 of datetime.iso8601 type vereist (die bestaan niet als PHP-eigen types)</para>
118 </listitem>
119 <listitem>
120 <para>Als auto-conversie zou kunnen falen (b.v.: je wil een lege XML-RPC struct als parameter doorgeven. Lege structs worden als lege arrays voorgesteld in PHP. Indien je een lege array als parameter doorgeeft zal die
121 worden omgezet in een XML-RPC array vermits het geen associatieve array is)</para>
122 </listitem>
123 </itemizedlist>
124 </para>
125 <para>
126 Er zijn 2 manieren waarop je een <code>Zend_XmlRpc_Value</code> object kan maken: expliciet (de constructor van het object
127 aanroepen) of door de statische functie <code>Zend_XmlRpc_Value::getXmlRpcValue()</code> met de vereiste XML-RPC type constante aan te roepen.
128 </para>
129 <table>
130 <title><code>Zend_XmlRpc_Value</code> objecten die de XML-RPC types voorstelt</title>
131 <tgroup cols="3">
132 <thead>
133 <row>
134 <entry>XML-RPC type</entry>
135 <entry>Overeenkomstige <code>Zend_XmlRpc_Value</code> constante</entry>
136 <entry><code>Zend_XmlRpc_Value</code> object</entry>
137 </row>
138 </thead>
139 <tbody>
140 <row>
141 <entry>int</entry>
142 <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_INTEGER</code></entry>
143 <entry><code>Zend_XmlRpc_Value_Integer</code></entry>
144 </row>
145 <row>
146 <entry>double</entry>
147 <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_DOUBLE</code></entry>
148 <entry><code>Zend_XmlRpc_Value_Double</code></entry>
149 </row>
150 <row>
151 <entry>boolean</entry>
152 <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_BOOLEAN</code></entry>
153 <entry><code>Zend_XmlRpc_Value_Boolean</code></entry>
154 </row>
155 <row>
156 <entry>string</entry>
157 <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_STRING</code></entry>
158 <entry><code>Zend_XmlRpc_Value_String</code></entry>
159 </row>
160 <row>
161 <entry>base64</entry>
162 <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64</code></entry>
163 <entry><code>Zend_XmlRpc_Value_Base64</code></entry>
164 </row>
165 <row>
166 <entry>dateTime.iso8601</entry>
167 <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_DATETIME</code></entry>
168 <entry><code>Zend_XmlRpc_Value_DateTime</code></entry>
169 </row>
170 <row>
171 <entry>array</entry>
172 <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_ARRAY</code></entry>
173 <entry><code>Zend_XmlRpc_Value_Array</code></entry>
174 </row>
175 <row>
176 <entry>struct</entry>
177 <entry><code>Zend_XmlRpc_Value::XMLRPC_TYPE_STRUCT</code></entry>
178 <entry><code>Zend_XmlRpc_Value_Struct</code></entry>
179 </row>
180 </tbody>
181 </tgroup>
182 </table>
183 <programlisting role="php"><![CDATA[<?php
185 /** 2 parameters worden aan deze procedure doorgegeven
186 * - De eerste parameter is een XML-RPC base64 type dat werd gemaakt door de statische functie Zend_XmlRpc_Value::getXmlRpcValue() aan te roepen
187 * - De tweede parameter is een XML-RPC structuur die expliciet werd gemaakt
188 */
190 $p1 = Zend_XmlRpc_Value::getXmlRpcValue('encoded string', Zend_XmlRpc_Value::XMLRPC_TYPE_BASE64);
191 $p2 = new Zend_XmlRpc_Value_Struct(array('name' => 'Joe', 'age' => 30));
193 $service->serviceProcedure($p1, $p2);
195 ?>]]>
196 </programlisting>
197 <para>
198 <note>
199 <para>De waarde van de parameter word nog steeds als een PHP variabele gegeven maar zal worden omgezet naar het gespecifieerde type door de PHP conversietechnieken te gebruiken (b.v.: als een string als waarde aan het <code>Zend_XmlRpc_Value_Integer</code> object wordt gegeven zal het worden omgezet door <code>(int)$value</code>) toe te passen).</para>
200 </note>
201 </para>
202 </sect3>
203 <sect3 id='zend.xmlrpc.client.parameters.as_xml'>
204 <title>Een XML string in een XML-RPC parameter "parsen"</title>
205 <para>
206 Deze methode van parameters doorgeven word intern in het <code>Zend_XmlRpc</code> pakket gebruikt en word niet aangeraden.
207 </para>
208 <para>
209 Indien je toch deze methode moet gebruiken zou je de statische functie <code>Zend_XmlRpc_Value::getXmlRpcValue()</code> moeten gebruiken om een string in een <code>Zend_XmlRpc_Value</code> object te gieten die het overeenkomstige XML-RPC type voorstelt. Je zou 2 parameters aan de <code>Zend_XmlRpc_Value::getXmlRpcValue()</code> functie moeten doorgeven: de XML string en de <code>Zend_XmlRpc_Value::XML_STRING</code> constante.
210 </para>
211 </sect3>
212 </sect2>
213 <sect2 id="zend.xmlrpc.client.wsdl">
214 <title>Hints geven voor parameter types</title>
215 <para>
216 Het voornaamste verschil tussen XML-RPC en SOAP web services is het WDSL bestand. Het SOAP protocol heeft meestal een WDSL bestand dat de interface van de web service beschrijft. Aan de hand van deze interface weet de SOAP client welke de benodigde parameter types zijn die naar de server moeten worden gestuurd en wat het type is van de teruggegeven waarde.
217 Zonder het WDSL bestand zou de gebruiker een probleem kunnen hebben de types te kennen.
218 </para>
219 <para>
220 De oplossing van het XML-RPC protocol is het gebruik van een speciale procedure van de service die <code>system.methodSignature</code> word genoemd. Deze procedure krijgt een procedurenaam als parameter aangegeven en geeft dan de handtekening van de gegeven procedure terug. De handtekening bevat het nodige type van de parameters en de waarde die wordt teruggegeven door de procedure.
221 </para>
222 <note>
223 <para>Niet alle XML-RPC server verstaan de speciale <code>system.methodSignature</code> procedure. Servers die dit niet verstaan bieden geen support voor het geven van hints voor types.</para>
224 </note>
225 <para>
226 <code>Zend_XmlRpc_Client</code> implementeert een soort van 'WSDL' type bestand voor XML-RPC server die de <code>system.methodSignature</code> procedure gebruiken.
227 Indien gevraagd zal <code>Zend_XmlRpc_Client</code> een lijst van alle procedures van een XML-RPC server aanvragen en alle handtekeningen van die procedures en zal die data opslaan in een XML bestand (gelijk aan het SOAP WSDL bestand).
228 Als je dan dezelfde XML-RPC server opnieuw gebruikt kan je het XML bestand doorgeven en <code>Zend_XmlRpc_Client</code> zal hints geven voor het type van alle parameters voor de aangevraagde procedure aan de hand van de handtekening ervan.
229 </para>
230 <para>
231 Het XML bestand met de procedurehandtekeningen wordt gemaakt door de <code>Zend_XmlRpc_Client::__getMethodsXml()</code> functie aan te roepen. Die geeft een XML string terug die alle data van de handtekening bevat.
232 Om een bestaand handtekening XML bestand aan te duiden kan de gebruiker de XML data als parameter aan de contructor van <code>Zend_XmlRpc_Client</code> doorgeven of de <code>Zend_XmlRpc_Client::__setMethodsXml()</code> functie aanroepen.
233 </para>
234 <example>
235 <title>Een XML-RPC service aanroepen met type hints</title>
236 <programlisting role="php"><![CDATA[<?php
238 /**
239 * Verbinden met een XML-RPC server, en zijn handtekening bestand opslaan (het equivalent
240 * van een SOAP WSDL bestand)
241 */
242 require_once 'Zend/XmlRpc/Client.php';
244 $service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc');
246 file_put_contents('/tmp/xmlrpc-signatures/example.xml', $service->__getMethodsXml());
248 /* Het $service object bevat alle handtekeningen van de XML-RPC server. Wanneer de serviceProcedure word opgeroepen zal zijn parameter ($param) naar het juiste type worden omgezet aan de hand van de handtekening van de procedure.
249 */
250 $service->serviceProcedure($param);
252 ?>]]>
253 </programlisting>
254 <programlisting role="php"><![CDATA[<?php
256 /**
257 * Verbinden met een XML-RPC server, gebruik makend van een bestaand handtekeningbestand. Zo verzekeren
258 * we ons ervan dat de doorgegeven parameters van het juiste type zijn.
259 */
260 require_once 'Zend/XmlRpc/Client.php';
262 $signature_file_xml = file_get_contents('/tmp/xmlrpc-signatures/example.xml');
263 $service = new Zend_XmlRpc_Client('http://www.example.org/xmlrpc', 'namespace', $signature_file_xml);
265 /* Het $service object bevat alle handtekeningen van de XML-RPC server. Wanneer de serviceProcedure word opgeroepen zal zijn parameter ($param) naar het juiste type worden omgezet aan de hand van de handtekening van de procedure.
266 */
267 $service->serviceProcedure($param);
269 ?>]]>
270 </programlisting>
271 </example>
272 </sect2>
273 <sect2 id="zend.xmlrpc.client.response">
274 <title>Het antwoord terugkrijgen</title>
275 <para>
276 De XML-RPC procedure geeft een waarde terug met een XML-RPC type.
277 De <code>Zend_XmlRpc_Client</code> methode die een XML-RPC procedure aanroept geeft een waarde terug met een PHP-eigen type die werd verkregen vanaf het teruggegeven XML-RPC type.
278 </para>
279 <para>
280 Je kan de <code>Zend_XmlRpc_Client::__getResponse()</code> functie gebruiken om de teruggegeven waarde te verkrijgen van de aangevraagde procedure.
281 De <code>__getResponse()</code> functie krijgt een parameter die het type van de teruggegeven waarde aanduidt.
282 De antwoordopties zijn:
283 <itemizedlist>
284 <listitem>
285 <para><code>Zend_XmlRpc_Client::RESPONSE_PHP_NATIVE</code> - Geef de terugegeven waarde van de procedure als een PHP-eigen waarde terug (zet het XML-RPC type om naar een PHP type).</para>
286 </listitem>
287 <listitem>
288 <para><code>Zend_XmlRpc_Client::RESPONSE_XML_STRING</code> - Geef de XML string voorstelling van het XML-RPC antwoord terug.</para>
289 </listitem>
290 <listitem>
291 <para><code>Zend_XmlRpc_Client::RESPONSE_ZXMLRPC_OBJECT</code> - Geef een <code>Zend_XmlRpc_Value</code> object terug die het teruggegeven XML-RPC type voorstelt.</para>
292 </listitem>
293 </itemizedlist>
294 </para>
295 <programlisting role="php"><![CDATA[<?php
297 $service->serviceProcedure();
299 $response = $service->__getResponse();
300 // $response is de PHP variabele omgezet van het type van de teruggegeven XML-RPC waarde
302 $response = $service->__getResponse(ZXmlRpcClient::RESPONSE_XML_STRING);
303 // $response is een string die de XML bevat die de door de procedure teruggegeven waarde voorstelt
305 $response = $service->__getResponse(ZXmlRpcClient::RESPONSE_ZXMLRPC_OBJECT);
306 // $response is een Zend_XmlRpc_Value instantie die de door de procedure teruggegeven waarde voorstelt
308 ?>]]>
309 </programlisting>
310 </sect2>
311 </sect1>
312 <!--
313 vim:se ts=4 sw=4 et:
314 -->