documentation/manual/de/module_specs/Zend_Http_Response.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21826 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.http.response">
   5     <title>Zend_Http_Response</title>
   6
   7     <sect2 id="zend.http.response.introduction">
   8         <title>Einführung</title>
   9
  10         <para>
  11             <classname>Zend_Http_Response</classname> stellt den einfachen Zugriff auf eine
  12             <acronym>HTTP</acronym> Rückantwort sowie einige statische Methoden zum Analysieren der
  13             <acronym>HTTP</acronym> Rückantworten bereit. Normalerweise wird
  14             <classname>Zend_Http_Response</classname> als ein Objekt verwendet, dass von einer
  15             <classname>Zend_Http_Client</classname> Anfrage zurückgegeben wurde.
  16         </para>
  17
  18         <para>
  19             In den meisten Fällen wird ein <classname>Zend_Http_Response</classname> Objekt über die
  20             fromString() Methode instanziert, die einen String liest, der eine
  21             <acronym>HTTP</acronym> Rückantwort enthält und ein
  22             <classname>Zend_Http_Response</classname> Objekt zurückgibt.
  23
  24             <example id="zend.http.response.introduction.example-1">
  25                 <title>Ein Zend_Http_Response Object über die factory Methode instanzieren</title>
  26
  27                 <programlisting language="php"><![CDATA[
  28 $str = '';
  29 $sock = fsockopen('www.example.com', 80);
  30 $req =     "GET / HTTP/1.1\r\n" .
  31         "Host: www.example.com\r\n" .
  32         "Connection: close\r\n" .
  33         "\r\n";
  34
  35 fwrite($sock, $req);
  36 while ($buff = fread($sock, 1024))
  37     $str .= $sock;
  38
  39 $response = Zend_Http_Response::fromString($str);
  40 ]]></programlisting>
  41             </example>
  42         </para>
  43
  44         <para>
  45             Man kann auch die Konstruktormethode verwenden, um ein neues Response Objekt zu
  46             erstellen, indem man alle Parameter für die Antwort angibt:
  47         </para>
  48
  49         <para>
  50             <code>
  51                 public function __construct($code, $headers, $body = null, $version = '1.1',
  52                 $message = null)
  53             </code>
  54         </para>
  55
  56         <itemizedlist>
  57             <listitem>
  58                 <para>
  59                     <varname>$code</varname>: Der <acronym>HTTP</acronym> Antwortcode(eg. 200, 404,
  60                     etc.)
  61                 </para>
  62             </listitem>
  63
  64             <listitem>
  65                 <para>
  66                     <varname>$headers</varname>: Ein assoziatives Array mit <acronym>HTTP</acronym>
  67                     Antwort Headers (z.B. 'Host' => 'example.com')
  68                 </para>
  69             </listitem>
  70
  71             <listitem>
  72                 <para>
  73                     <varname>$body</varname>: Der Hauptteil der Antwort als String
  74                 </para>
  75             </listitem>
  76
  77             <listitem>
  78                 <para>
  79                     <varname>$version</varname>: Der Version der <acronym>HTTP</acronym> Antwort
  80                     (normalerweise 1.0 oder 1.1)
  81                 </para>
  82             </listitem>
  83
  84             <listitem>
  85                 <para>
  86                     <varname>$message</varname>: Die <acronym>HTTP</acronym> Rückantwort (z.B. 'OK',
  87                     'Internal Server Error'). Falls nicht angegeben, wird die Rückantwort anhand des
  88                     Antwortcode gesetzt.
  89                 </para>
  90             </listitem>
  91         </itemizedlist>
  92     </sect2>
  93
  94     <sect2 id="zend.http.response.testers">
  95         <title>Boolesche Testmethoden</title>
  96
  97         <para>
  98             Sobald ein <classname>Zend_Http_Response</classname> Objekt instantiert ist, stellt es
  99             mehrere Methoden bereit, die zum Testen des Typs der Antwort verwendet werden können.
 100             Diese geben alle ein boolesches <constant>TRUE</constant> oder
 101             <constant>FALSE</constant> zurück:
 102
 103             <itemizedlist>
 104                 <listitem>
 105                     <para>
 106                         <code>Boolean isSuccessful()</code>: Ob die Anfrage erfolgreoch war oder
 107                         nicht. Gibt <constant>TRUE</constant> für <acronym>HTTP</acronym> 1xx und
 108                         2xx Antwortcodes zurück.
 109                     </para>
 110                 </listitem>
 111
 112                 <listitem>
 113                     <para>
 114                         <code>Boolean isError()</code>: Ob der Antwortcode auf einen Fehler
 115                         rückschließen lässt oder nicht. Gibt <constant>TRUE</constant> für
 116                         <acronym>HTTP</acronym> 4xx (Client Fehler) und 5xx (Server Fehler)
 117                         Antwortcodes zurück.
 118                     </para>
 119                 </listitem>
 120
 121                 <listitem>
 122                     <para>
 123                         <code>Boolean isRedirect()</code>: Ob die Antwort eine Weiterleitung ist
 124                         oder nicht. Gibt <constant>TRUE</constant> für <acronym>HTTP</acronym> 3xx
 125                         Antwortcodes zurück.
 126                     </para>
 127                 </listitem>
 128             </itemizedlist>
 129
 130             <example id="zend.http.response.testers.example-1">
 131                 <title>Die isError() Method verwenden, um eine Antwort zu validieren</title>
 132
 133                 <programlisting language="php"><![CDATA[
 134 if ($response->isError()) {
 135   echo "Error transmitting data.\n"
 136   echo "Server reply was: " . $response->getStatus() .
 137        " " . $response->getMessage() . "\n";
 138 }
 139 // .. verarbeite die Antwort hier...
 140 ]]></programlisting>
 141             </example>
 142         </para>
 143     </sect2>
 144
 145     <sect2 id="zend.http.response.acessors">
 146         <title>Zugriffsmethoden</title>
 147
 148         <para>
 149             Der Hauptzweck eines Response Okjektes ist der einfache Zugriff auf diverse
 150             Antwortparameter.
 151
 152             <itemizedlist>
 153                 <listitem>
 154                     <para>
 155                         <code>int getStatus()</code>: Erhalte den <acronym>HTTP</acronym>
 156                         Antwortstatuscode (z.B. 200, 504, etc.) zurück
 157                     </para>
 158                 </listitem>
 159
 160                 <listitem>
 161                     <para>
 162                         <code>string getMessage()</code>: Erhalte die <acronym>HTTP</acronym>
 163                         Antwortstatus Meldung (z.B. "Not Found", "Authorization Required") zurück.
 164                     </para>
 165                 </listitem>
 166
 167                 <listitem>
 168                     <para>
 169                         <code>string getBody()</code>: Erhalte den kompletten dekodierten Hauptteil
 170                         der <acronym>HTTP</acronym> Antwort zurück
 171                     </para>
 172                 </listitem>
 173
 174                 <listitem>
 175                     <para>
 176                         <code>string getRawBody()</code>: Erhalte die rohen, möglicherweise
 177                         kodierten Hauptteil der <acronym>HTTP</acronym> Antwort zurück. Wenn der
 178                         Hauptteil z.B. mittels GZIP kodiert wurde, wird er nicht dekodiert.
 179                     </para>
 180                 </listitem>
 181
 182                 <listitem>
 183                     <para>
 184                         <code>array getHeaders()</code>: Erhalte die <acronym>HTTP</acronym> Antwort
 185                         Header als assoziatives Array (z.B. 'Content-type' => 'text/html') zurück.
 186                     </para>
 187                 </listitem>
 188
 189                 <listitem>
 190                     <para>
 191                         <code>string|array getHeader($header)</code>: Erhalte einen spezifischen
 192                         <acronym>HTTP</acronym> Antwort Header zurück, der durch $header angegeben
 193                         wird.
 194                     </para>
 195                 </listitem>
 196
 197                 <listitem>
 198                     <para>
 199                         <code>string getHeadersAsString($status_line = true, $br = "\n")</code>:
 200                         Erhalte den kompletten Header Satz als String zurück. Wenn $status_line
 201                         auf <constant>TRUE</constant> gesetzt ist (Standardwert), wird die erste
 202                         Statuszeile (z.B. "HTTP/1.1 200 OK") ebenfalls zurück gegeben. Die Zeilen
 203                         werden durch den $br Parameter umgebrochen (kann z.B. "&lt;br /&gt;" sein).
 204                     </para>
 205                 </listitem>
 206
 207                 <listitem>
 208                     <para>
 209                         <code>string asString($br = "\n")</code>: Erhalte die komplette Rückantwort
 210                         als String zurück. Die Zeilen werden durch den $br Parameter umgebrochen
 211                         (kann z.B. "&lt;br /&gt;" sein). Man kann auch die matische __toString()
 212                         Methode verwenden wenn man das Objekt in einen String casten will. Diese
 213                         wird dann auf asString() weiterleiten
 214                     </para>
 215                 </listitem>
 216             </itemizedlist>
 217
 218             <example id="zend.http.response.acessors.example-1">
 219                 <title>Zend_Http_Response Zugriffsmethoden verwenden</title>
 220
 221                 <programlisting language="php"><![CDATA[
 222 if ($response->getStatus() == 200) {
 223   echo "The request returned the following information:<br />";
 224   echo $response->getBody();
 225 } else {
 226   echo "An error occurred while fetching data:<br />";
 227   echo $response->getStatus() . ": " . $response->getMessage();
 228 }
 229 ]]></programlisting>
 230             </example>
 231
 232             <note>
 233                 <title>Immer die Rückgabewerte prüfen</title>
 234
 235                 <para>
 236                     Weil eine Antwort mehrere Instanzen des selben Headers beinhalten kann, können
 237                     die getHeader() Methode und getHeaders() Methode entweder einen einzelnen String
 238                     oder ein Array mit Strings für jeden Header zurückgeben. Man sollte immer
 239                     prüfen, ob der Rückgabewert ein String oder ein Array ist.
 240                 </para>
 241             </note>
 242
 243             <example id="zend.http.response.acessors.example-2">
 244                 <title>Auf Antwort Header zugreifen</title>
 245
 246                 <programlisting language="php"><![CDATA[
 247 $ctype = $response->getHeader('Content-type');
 248 if (is_array($ctype)) $ctype = $ctype[0];
 249
 250 $body = $response->getBody();
 251 if ($ctype == 'text/html' || $ctype == 'text/xml') {
 252   $body = htmlentities($body);
 253 }
 254
 255 echo $body;
 256 ]]></programlisting>
 257             </example>
 258         </para>
 259     </sect2>
 260
 261     <sect2 id="zend.http.response.static_parsers">
 262         <title>Statische HTTP Antwortanalysierer</title>
 263
 264         <para>
 265             Die <classname>Zend_Http_Response</classname> Klasse beinhaltet auch verschiedene,
 266             intern verwendete Methoden für die Verarbeitung und Analyse der <acronym>HTTP</acronym>
 267             Rückantworten bereit. Diese Methoden sind alle als statische Methoden eingerichtet, so
 268             dass man sie extern verwenden kann, ohne dass man ein Response Objekt instanzierebn muss
 269             und nur einen bestimmten Teil der Antwort extrahieren möchte.
 270
 271             <itemizedlist>
 272                 <listitem>
 273                     <para>
 274                         <code>int Zend_Http_Response::extractCode($response_str)</code>: Extrahiere
 275                         den <acronym>HTTP</acronym> Antwortcode (z.B. 200 oder 404) von
 276                         $response_str und gebe ihn zurück.
 277                     </para>
 278                 </listitem>
 279
 280                 <listitem>
 281                     <para>
 282                         <code>string Zend_Http_Response::extractMessage($response_str)</code>:
 283                         Extrahiere die <acronym>HTTP</acronym> Rückantwort (z.B. "OK" oder
 284                         "File Not Found") von $response_str und gebe sie zurück.
 285                     </para>
 286                 </listitem>
 287
 288                 <listitem>
 289                     <para>
 290                         <code>string Zend_Http_Response::extractVersion($response_str)</code>: :
 291                         Extrahiere die <acronym>HTTP</acronym> Version (z.B. 1.1 oder 1.0) von
 292                         $response_str und gebe sie zurück.
 293                     </para>
 294                 </listitem>
 295
 296                 <listitem>
 297                     <para>
 298                         <code>array Zend_Http_Response::extractHeaders($response_str)</code>:
 299                         Extrahiere die <acronym>HTTP</acronym> Antwort Header von response_str und
 300                         gebe sie in einem Array zurück.
 301                     </para>
 302                 </listitem>
 303
 304                 <listitem>
 305                     <para>
 306                         <code>string Zend_Http_Response::extractBody($response_str)</code>:
 307                         Extrahiere den <acronym>HTTP</acronym> Antworthauptteil aus $response_str
 308                         und gebe ihn zurück.
 309                     </para>
 310                 </listitem>
 311
 312                 <listitem>
 313                     <para>
 314                         <code>string Zend_Http_Response::responseCodeAsText($code = null, $http11 =
 315                         true)</code>: Erhalte die Standard <acronym>HTTP</acronym> Rückantwort für
 316                         einen Antwortcode $code. Zum Beispiel wird "Internal Server Error"
 317                         zurückgegeben, wenn $code gleich 500 ist. Wenn $http11 gleich
 318                         <constant>TRUE</constant> ist (Standard), werden die
 319                         <acronym>HTTP</acronym>/1.1 Standardantworten zurück gegeben, andernfalls
 320                         die <acronym>HTTP</acronym>/1.0 Antworten. Wird $code nicht angegeben, wird
 321                         diese Methode alle bekannten <acronym>HTTP</acronym> Antwortcodes als
 322                         assoziatives Array (code => message) zurückgeben.
 323                     </para>
 324                 </listitem>
 325             </itemizedlist>
 326         </para>
 327
 328         <para>
 329             Neben der Analysemethoden beinhaltet die Klasse auch einen Satz von Dekodieren für
 330             allgemein <acronym>HTTP</acronym> Antwort Transferkodierungen:
 331
 332             <itemizedlist>
 333                 <listitem>
 334                     <para>
 335                         <code>string Zend_Http_Response::decodeChunkedBody($body)</code>: Dekodiere
 336                         einen kompletten "Content-Transfer-Encoding: Chunked" Hauptteil
 337                     </para>
 338                 </listitem>
 339
 340                 <listitem>
 341                     <para>
 342                         <code>string Zend_Http_Response::decodeGzip($body)</code>: Dekodiere
 343                         einen "Content-Encoding: gzip" Hauptteil
 344                     </para>
 345                 </listitem>
 346
 347                 <listitem>
 348                     <para>
 349                         <code>string Zend_Http_Response::decodeDeflate($body)</code>: Dekodiere
 350                         einen "Content-Encoding: deflate" Hauptteil
 351                     </para>
 352                 </listitem>
 353             </itemizedlist>
 354         </para>
 355     </sect2>
 356 </sect1>