1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.rest.client">
<title>Zend_Rest_Client</title>
<sect2 id="zend.rest.client.introduction">
<title>Einführung</title>
<para>
Die Verwendung von <classname>Zend_Rest_Client</classname> ist sehr ähnlich der
Verwendung von <code>SoapClient</code> Objekten (<ulink
url="http://www.php.net/soap">SOAP Web Service Erweiterung</ulink>). Man kann
einfach die REST Service Prozeduren als <classname>Zend_Rest_Client</classname> Methoden
aufrufen. Spezifiziere die komplette Adresse des Services im Constructor von
<classname>Zend_Rest_Client</classname>.
</para>
<example id="zend.rest.client.introduction.example-1">
<title>Eine Basis REST Anfrage</title>
<programlisting language="php"><![CDATA[
/**
* Verbinden zum framework.zend.com Server und eine Begrüßung empfangen
*/
$client = new Zend_Rest_Client('http://framework.zend.com/rest');
echo $client->sayHello('Davey', 'Day')->get(); // "Servus Davey, guten Tag"
]]></programlisting>
</example>
<note>
<title>Unterschiede im Aufruf</title>
<para>
<classname>Zend_Rest_Client</classname> versucht, dass die entfernten Methoden, so
weit wie möglich, wie die nativen Methoden aussehen, wobei der einzige Unterschied
darin besteht, dass der Methodenaufruf mit <methodname>get()</methodname>,
<methodname>post()</methodname>, <methodname>put()</methodname> oder
<methodname>delete()</methodname> erfolgen muß. Dieser Aufruf kann entweder über
Methoden Verkettung oder in eigenen Methodenaufrufen erfolgen:
</para>
<programlisting language="php"><![CDATA[
$client->sayHello('Davey', 'Tag');
echo $client->get();
]]></programlisting>
</note>
</sect2>
<sect2 id="zend.rest.client.return">
<title>Antworten</title>
<para>
Alle Anfragen die über <classname>Zend_Rest_Client</classname> gemacht wurden,
liefern ein <classname>Zend_Rest_Client_Response</classname> Objekt zurück. Dieses
Objekt hat viele Eigenschaften, was es einfacher macht, auf die Ergebnisse zuzugreifen.
</para>
<para>
Wenn ein Service auf <classname>Zend_Rest_Server</classname> basiert, kann
<classname>Zend_Rest_Client</classname> einige Annahmen über die Antwort treffen,
inklusive dem Antwort Status (erfolgreich oder fehlerhaft) und den Rückgabetyp.
</para>
<example id="zend.rest.client.return.example-1">
<title>Antwort Status</title>
<programlisting language="php"><![CDATA[
$result = $client->sayHello('Davey', 'Tag')->get();
if ($result->isSuccess()) {
echo $result; // "Hallo Davey, guten Tag"
}
]]></programlisting>
</example>
<para>
Im obigen Beispiel kann man sehen, dass das Ergebnis der Anfrage als Objekt verwendet
wird, um <methodname>isSuccess()</methodname> aufzurufen. Mithilfe der magischen
<methodname>__toString()</methodname>-Methode kann man das Objekt bzw. das Ergebnis
ausgeben (<code>echo</code>). <classname>Zend_Rest_Client_Response</classname> erlaubt
die Ausgabe jedes skalaren Wertes. Für komplexe Typen, kann entweder die Array- oder die
Objektschreibweise verwendet werden.
</para>
<para>
Wenn trotzdem ein Service abgefragt wird, der nicht
<classname>Zend_Rest_Server</classname> verwendet, wird sich das
<classname>Zend_Rest_Client_Response</classname> Objekt mehr wie ein
<code>SimpleXMLElement</code> verhalten. Um die Dinge trotzdem einfacher zu gestalten,
wird das <acronym>XML</acronym> automatisch abgefragt, indem XPath verwendet wird, wenn
die Eigenschaft nicht von direkter Abstammung des Dokument Root-Elements ist.
Zusätzlich, wenn auf eine Eigenschaft als Methode zugegriffen wird, empfängt man den
<acronym>PHP</acronym> Wert für das Objekt, oder ein Array mit den
<acronym>PHP</acronym> Wert Ergebnissen.
</para>
<example id="zend.rest.client.return.example-2">
<title>Technorati's REST Service verwenden</title>
<programlisting language="php"><![CDATA[
$technorati = new Zend_Rest_Client('http://api.technorati.com/bloginfo');
$technorati->key($key);
$technorati->url('http://pixelated-dreams.com');
$result = $technorati->get();
echo $result->firstname() .' '. $result->lastname();
]]></programlisting>
</example>
<example id="zend.rest.client.return.example-3">
<title>Beispiel Technorati Antwort</title>
<programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="utf-8"?>
<!-- generator="Technorati API version 1.0 /bloginfo" -->
<!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN"
"http://api.technorati.com/dtd/tapi-002.xml">
<tapi version="1.0">
<document>
<result>
<url>http://pixelated-dreams.com</url>
<weblog>
<name>Pixelated Dreams</name>
<url>http://pixelated-dreams.com</url>
<author>
<username>DShafik</username>
<firstname>Davey</firstname>
<lastname>Shafik</lastname>
</author>
<rssurl>
http://pixelated-dreams.com/feeds/index.rss2
</rssurl>
<atomurl>
http://pixelated-dreams.com/feeds/atom.xml
</atomurl>
<inboundblogs>44</inboundblogs>
<inboundlinks>218</inboundlinks>
<lastupdate>2006-04-26 04:36:36 GMT</lastupdate>
<rank>60635</rank>
</weblog>
<inboundblogs>44</inboundblogs>
<inboundlinks>218</inboundlinks>
</result>
</document>
</tapi>
]]></programlisting>
</example>
<para>
Hier greifen wir auf die <code>firstname</code> und <code>lastname</code> Eigenschaften
zu. Selbst wenn diese keine Top-Level Elemente sind, werden Sie automatisch
zurückgegeben, wenn auf sie durch ihren Namen zugegriffen wird.
</para>
<note>
<title>Mehrere Elemente</title>
<para>
Wenn beim Zugriff, über einen Namen, mehrere Elemente mit demselben Namen gefunden
werden, wird ein Array von SimpleXML-Elementen zurückgegeben. Beim Zugriff über die
Methodenschreibweise wird ein Array von <acronym>PHP</acronym> Werten zurückgegeben.
</para>
</note>
</sect2>
<sect2 id="zend.rest.client.args">
<title>Anfrage Argumente</title>
<para>
Wenn man eine Anfrage an einen Server sendet, welcher nicht auf
<classname>Zend_Rest_Server</classname> basiert, sind die Chancen groß, dass man mehrere
Argumente mit der Anfrage senden muß. Das wird durchgeführt, indem man eine Methode mit
dem Namen des Arguments aufruft und den Wert, als das erste (und einzige) Argument
übergibt. Jeder dieser Methodenaufrufe, gibt das Objekt selbst zurück, was Verkettung
oder "flüssige" Verwendung erlaubt. Der erste Aufruf, oder das erste Argument, das
übergeben wird, wenn man mehr als ein Argument übergeben will, wird immer als die
Methode angenommen wenn ein <classname>Zend_Rest_Server</classname> Service aufgerufen
wird.
</para>
<example id="zend.rest.client.args.example-1">
<title>Anfrage Argumente setzen</title>
<programlisting language="php"><![CDATA[
$client = new Zend_Rest_Client('http://example.org/rest');
$client->arg('value1');
$client->arg2('value2');
$client->get();
// oder
$client->arg('value1')->arg2('value2')->get();
]]></programlisting>
</example>
<para>
Beide Varianten im obigen Beispiel, ergeben die folgenden get-Argumente:
<code>?method=arg&arg1=value1&arg=value1&arg2=value2</code>
</para>
<para>
Es gilt zu bemerken, dass der erste Aufruf von <code>$client->arg('value1');</code> in
beidem resultiert: <code>method=arg&arg1=value1</code> und <code>arg=value1</code>.
Es ist so, dass <classname>Zend_Rest_Server</classname> die Anfrage korrekt versteht,
ohne dass vordefiniertes Wissen über das Service benötigt wird.
</para>
<warning>
<title>Striktheit von Zend_Rest_Client</title>
<para>
Jeder REST Service der strikt in seinen Argumenten ist, die er empfängt, wird wegen
dem oben beschriebenen Verhalten bei der Verwendung von
<classname>Zend_Rest_Client</classname> fehlschlagen. Das ist keine gewöhnliche
Praxis und sollte keine Probleme verursachen.
</para>
</warning>
</sect2>
</sect1>
|
