repo_zf1/documentation/manual/de/module_specs/Zend_Http_Response.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: 22747 -->
<sect1 id="zend.http.response">
    <title>Zend_Http_Response</title>

    <sect2 id="zend.http.response.introduction">
        <title>Einführung</title>

        <para>
            <classname>Zend_Http_Response</classname> stellt den einfachen Zugriff auf eine
            <acronym>HTTP</acronym>-Rückantwort sowie einige statische Methoden zur Analyse der
            <acronym>HTTP</acronym>-Rückantworten bereit. Normalerweise wird
            <classname>Zend_Http_Response</classname> als ein Objekt verwendet, das von einer
            <classname>Zend_Http_Client</classname>-Anfrage zurückgegeben wurde.
        </para>

        <para>
            In den meisten Fällen wird ein <classname>Zend_Http_Response</classname>-Objekt über die
            Methode fromString() instanziert, die einen String liest, der eine
            <acronym>HTTP</acronym>-Rückantwort enthält und ein
            <classname>Zend_Http_Response</classname>-Objekt zurückgibt.

            <example id="zend.http.response.introduction.example-1">
                <title>Ein Zend_Http_Response-Objekt über die Factory-Methode instanzieren</title>

                <programlisting language="php"><![CDATA[
$str = '';
$sock = fsockopen('www.example.com', 80);
$req =     "GET / HTTP/1.1\r\n" .
        "Host: www.example.com\r\n" .
        "Connection: close\r\n" .
        "\r\n";

fwrite($sock, $req);
while ($buff = fread($sock, 1024))
    $str .= $sock;

$response = Zend_Http_Response::fromString($str);
]]></programlisting>
            </example>
        </para>

        <para>
            Man kann auch die Konstruktormethode verwenden, um ein neues Zend_Http_Response-Objekt
            zu erstellen, indem man alle Parameter für die Antwort angibt:
        </para>

        <para>
            <command>public function __construct($code, $headers, $body = null, $version = '1.1',
                $message = null)</command>
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <varname>$code</varname>: Der <acronym>HTTP</acronym>-Antwortcode(eg. 200, 404,
                    etc.)
                </para>
            </listitem>

            <listitem>
                <para>
                    <varname>$headers</varname>: Ein assoziatives Array mit <acronym>HTTP</acronym>
                    Antwort Headers (z.B. 'Host' => 'example.com')
                </para>
            </listitem>

            <listitem>
                <para>
                    <varname>$body</varname>: Der Hauptteil der Antwort als String
                </para>
            </listitem>

            <listitem>
                <para>
                    <varname>$version</varname>: Der Version der <acronym>HTTP</acronym>-Antwort
                    (normalerweise 1.0 oder 1.1)
                </para>
            </listitem>

            <listitem>
                <para>
                    <varname>$message</varname>: Die <acronym>HTTP</acronym>-Rückantwort (z.B. 'OK',
                    'Internal Server Error'). Falls nicht angegeben, wird die Rückantwort anhand des
                    Antwortcode gesetzt.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.http.response.testers">
        <title>Boolesche Testmethoden</title>

        <para>
            Sobald ein <classname>Zend_Http_Response</classname>-Objekt instanziert ist, stellt es
            mehrere Methoden bereit, die zum Testen des Typs der Antwort verwendet werden können.
            Diese geben alle ein boolesches <constant>TRUE</constant> oder
            <constant>FALSE</constant> zurück:

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>isSuccessful()</methodname>: Ob die Anfrage erfolgreich war oder
                        nicht. Gibt <constant>TRUE</constant> für <acronym>HTTP</acronym> 1xx und
                        2xx Antwortcodes zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>isError()</methodname>: Ob der Antwortcode auf einen Fehler
                        rückschließen lässt oder nicht. Gibt <constant>TRUE</constant> für
                        <acronym>HTTP</acronym> 4xx (Client Fehler) und 5xx (Server Fehler)
                        Antwortcodes zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>isRedirect()</methodname>: Ob die Antwort eine Weiterleitung ist
                        oder nicht. Gibt <constant>TRUE</constant> für <acronym>HTTP</acronym> 3xx
                        Antwortcodes zurück.
                    </para>
                </listitem>
            </itemizedlist>

            <example id="zend.http.response.testers.example-1">
                <title>Die Methode isError() verwenden, um eine Antwort zu validieren</title>

                <programlisting language="php"><![CDATA[
if ($response->isError()) {
  echo "Error transmitting data.\n"
  echo "Server reply was: " . $response->getStatus() .
       " " . $response->getMessage() . "\n";
}
// .. verarbeite die Antwort hier...
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.response.acessors">
        <title>Zugriffsmethoden</title>

        <para>
            Der Hauptzweck eines Zend_Http_Response-Objekts ist der einfache Zugriff auf diverse
            Antwortparameter.

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>getStatus()</methodname>: Erhalte den <acronym>HTTP</acronym>
                        Antwortstatuscode (z.B. 200, 504, etc.) zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getMessage()</methodname>: Erhalte die <acronym>HTTP</acronym>
                        Antwortstatus Meldung (z.B. "Not Found", "Authorization Required") zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getBody()</methodname>: Erhalte den kompletten dekodierten
                        Hauptteil der <acronym>HTTP</acronym>-Antwort zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getRawBody()</methodname>: Erhalte den rohen, möglicherweise
                        kodierten Hauptteil der <acronym>HTTP</acronym>-Antwort zurück. Wenn der
                        Hauptteil z.B. mittels GZIP kodiert wurde, wird er nicht dekodiert.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getHeaders()</methodname>: Erhalte die 
                        <acronym>HTTP</acronym>-Antwort-Header als assoziatives Array 
                        (z.B. 'Content-type' => 'text/html') zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getHeader($header)</methodname>: Erhalte einen spezifischen
                        <acronym>HTTP</acronym>-Antwort-Header zurück, der durch $header angegeben
                        wird.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getHeadersAsString($status_line, $br)</methodname>:
                        Erhalte den kompletten Header-Satz als String zurück. Wenn
                        <varname>$status_line</varname> auf <constant>TRUE</constant> gesetzt ist
                        (Standardwert), wird die erste Statuszeile (z.B. "HTTP/1.1 200 OK")
                        ebenfalls zurückgegeben. Die Zeilen werden durch den <varname>$br</varname>
                        Parameter umgebrochen (kann z.B. "&lt;br /&gt;" sein. Standardwert ist
                        "\n").
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>asString($br)</methodname>: Erhalte die komplette Rückantwort
                        als String zurück. Die Zeilen werden durch den Parameter $br umgebrochen
                        (kann z.B. "&lt;br /&gt;" sein. Standardwert ist "\n"). Man kann auch die
                        magische Methode <methodname>__toString()</methodname> verwenden, wenn man
                        das Objekt in einen String casten will. Diese wird dann auf
                        <methodname>asString()</methodname> weiterleiten.
                    </para>
                </listitem>
            </itemizedlist>

            <example id="zend.http.response.acessors.example-1">
                <title>Zend_Http_Response Zugriffsmethoden verwenden</title>

                <programlisting language="php"><![CDATA[
if ($response->getStatus() == 200) {
  echo "The request returned the following information:<br />";
  echo $response->getBody();
} else {
  echo "An error occurred while fetching data:<br />";
  echo $response->getStatus() . ": " . $response->getMessage();
}
]]></programlisting>
            </example>

            <note>
                <title>Immer die Rückgabewerte prüfen</title>

                <para>
                    Weil eine Antwort mehrere Instanzen desselben Headers beinhalten kann, können
                    die Methoden getHeader() und getHeaders() entweder einen einzelnen String
                    oder ein Array mit Strings für jeden Header zurückgeben. Man sollte immer
                    prüfen, ob der Rückgabewert ein String oder ein Array ist.
                </para>
            </note>

            <example id="zend.http.response.acessors.example-2">
                <title>Auf Antwort-Header zugreifen</title>

                <programlisting language="php"><![CDATA[
$ctype = $response->getHeader('Content-type');
if (is_array($ctype)) $ctype = $ctype[0];

$body = $response->getBody();
if ($ctype == 'text/html' || $ctype == 'text/xml') {
  $body = htmlentities($body);
}

echo $body;
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.response.static_parsers">
        <title>Statische HTTP-Antwortanalysierer</title>

        <para>
            Die Klasse <classname>Zend_Http_Response</classname> beinhaltet auch verschiedene,
            intern verwendete Methoden für die Verarbeitung und Analyse der 
            <acronym>HTTP</acronym>-Rückantworten. Diese Methoden sind alle als statische Methoden
            eingerichtet, so dass man sie extern verwenden kann, ohne dass man ein
            Zend_Http_Response-Objekt instanzieren muss und nur einen bestimmten Teil der Antwort
            extrahieren möchte.

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>Zend_Http_Response::extractCode($response_str)</methodname>:
                        Extrahiere den <acronym>HTTP</acronym>-Antwortcode (z.B. 200 oder 404) von
                        <varname>$response_str</varname> und gebe ihn zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>Zend_Http_Response::extractMessage($response_str)</methodname>:
                        Extrahiere die <acronym>HTTP</acronym>-Rückantwort (z.B. "OK" oder
                        "File Not Found") von <varname>$response_str</varname> und gebe sie zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>Zend_Http_Response::extractVersion($response_str)</methodname>:
                        Extrahiere die <acronym>HTTP</acronym>-Version (z.B. 1.1 oder 1.0) von
                        <varname>$response_str</varname> und gebe sie zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>Zend_Http_Response::extractHeaders($response_str)</methodname>:
                        Extrahiere die <acronym>HTTP</acronym>-Antwort-Header von
                        <varname>$response_str</varname> und gebe sie in einem Array zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>Zend_Http_Response::extractBody($response_str)</methodname>:
                        Extrahiere den <acronym>HTTP</acronym>-Antworthauptteil aus
                        <varname>$response_str</varname> und gebe ihn zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>Zend_Http_Response::responseCodeAsText($code,
                            $http11)</methodname>: Erhalte die Standard <acronym>HTTP</acronym>
                        Rückantwort für einen Antwortcode $code. Zum Beispiel wird "Internal Server
                        Error" zurückgegeben, wenn <varname>$code</varname> gleich 500 ist. Wenn
                        <varname>$http11</varname> gleich <constant>TRUE</constant> ist (Standard),
                        werden die <acronym>HTTP</acronym>/1.1 Standardantworten zurückgegeben,
                        andernfalls die <acronym>HTTP</acronym>/1.0 Antworten. Wird
                        <varname>$code</varname> nicht angegeben, wird diese Methode alle bekannten
                        <acronym>HTTP</acronym>-Antwortcodes als assoziatives Array (code =>
                        message) zurückgeben.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            Neben der Analysemethoden beinhaltet die Klasse auch einen Satz von Dekodierern für
            allgemeine <acronym>HTTP</acronym>-Antwort-Transferkodierungen:

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>Zend_Http_Response::decodeChunkedBody($body)</methodname>:
                        Dekodiere einen kompletten "Content-Transfer-Encoding: Chunked" Hauptteil
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>Zend_Http_Response::decodeGzip($body)</methodname>: Dekodiere
                        einen "Content-Encoding: gzip" Hauptteil
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>Zend_Http_Response::decodeDeflate($body)</methodname>: Dekodiere
                        einen "Content-Encoding: deflate" Hauptteil
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>
</sect1>