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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: 22743 -->
<sect1 id="zend.http.client">
    <title>Einführung</title>

    <para>
        <classname>Zend_Http_Client</classname> stellt eine einfache Schnittstelle für das
        Durchführen von Hyper-Text Transfer Protocol (HTTP) Anfragen.
        <classname>Zend_Http_Client</classname> unterstützt die meisten einfachen Funktionen, die
        man von einem <acronym>HTTP</acronym>-Client erwartet, sowie einige komplexere Funktionen,
        wie z.B. <acronym>HTTP</acronym>-Authentifizierung und Dateiuploads. Erfolgreiche Anfragen
        (und die meisten nicht erfolgreichen ebenfalls) liefern ein
        <classname>Zend_Http_Response</classname>-Objekt zurück, welches den Zugriff auf die Header
        und den Hauptteil der Antwort ermöglichen (siehe <link linkend="zend.http.response">diesen
            Abschnitt</link>).
    </para>

    <sect2 id="zend.http.client.usage">
        <title>Zend_Http_Client verwenden</title>

        <para>
            Der Klassenkonstruktor akzeptiert optional eine URL als seinen ersten Parameter (kann
            entweder ein String oder ein <classname>Zend_Uri_Http</classname>-Objekt sein) und ein
            Array oder <classname>Zend_Config</classname>-Objekt, welches Konfigurationsparameter
            enthält. Beides kann weggelassen und später durch Verwendung der Methoden setUri() und
            setConfig() gesetzt werden.

            <example id="zend.http.client.introduction.example-1">
                <title>Ein Zend_Http_Client Objekt instanzieren</title>

                <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client('http://example.org', array(
    'maxredirects' => 0,
    'timeout'      => 30));

// Dies macht genau dasselbe:
$client = new Zend_Http_Client();
$client->setUri('http://example.org');
$client->setConfig(array(
    'maxredirects' => 0,
    'timeout'      => 30));

// Man kann auch ein Zend_Config Objekt verwenden um die Konfiguration
// des Clients zu setzen
$config = new Zend_Config_Ini('httpclient.ini', 'secure');
$client->setConfig($config);
]]></programlisting>
            </example>

            <note>
                <para>
                    <classname>Zend_Http_Client</classname> verwendet
                    <classname>Zend_Uri_Http</classname> um URLs zu prüfen. Das bedeutet, dass einige
                    spezielle Zeichen wie das Pipe-Symbol ('|') oder das Karet Symbol ('^') in der
                    URL standardmäßig nicht akzeptiert werden. Das kann geändert werden, indem die
                    Option 'allow_unwise' von <classname>Zend_Uri</classname> auf
                    '<constant>TRUE</constant>' gesetzt wird. Siehe <link
                        linkend="zend.uri.validation.allowunwise">diesen Abschnitt</link> für mehr
                    Informationen.
                </para>
            </note>
        </para>
    </sect2>

    <sect2 id="zend.http.client.configuration">
        <title>Konfigurationsparameter</title>

        <para>
            Der Konstruktor und die Methode setConfig() akzeptieren ein assoziatives Array mit
            Konfigurationsparametern oder ein <classname>Zend_Config</classname>-Objekt. Das Setzen
            dieser Parameter ist optional, da alle einen Standardwert haben.

            <table id="zend.http.client.configuration.table">
                <title>Konfigurationsparameter von Zend_Http_Client</title>

                <tgroup cols="4">
                    <thead>
                        <row>
                            <entry>Parameter</entry>
                            <entry>Beschreibung</entry>
                            <entry>Erwartete Werte</entry>
                            <entry>Standardwert</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry>maxredirects</entry>
                            <entry>Maximale Anzahl von zu folgenden Umleitungen (0 = keine)</entry>
                            <entry>integer</entry>
                            <entry>5</entry>
                        </row>

                        <row>
                            <entry>strict</entry>

                            <entry>
                                Ob Prüfungen an Headernamen durchzuführen sind. Einige
                                Prüffunktionen werden übersprungen, wenn auf
                                <constant>FALSE</constant> gesetzt. Sollte normalerweise nicht
                                geändert werden.
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>TRUE</constant></entry>
                        </row>

                        <row>
                            <entry>strictredirects</entry>

                            <entry>
                                Ob beim Umleiten genau dem <acronym>RFC</acronym> zu folgen ist
                                (siehe <link linkend="zend.http.client.redirections">diesen
                                    Abschnitt</link>)
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>FALSE</constant></entry>
                        </row>

                        <row>
                            <entry>useragent</entry>

                            <entry>
                                String zur Identifizierung des User Agents (gesendet in den
                                Anfrageheadern)
                            </entry>

                            <entry>string</entry>
                            <entry>'Zend_Http_Client'</entry>
                        </row>

                        <row>
                            <entry>timeout</entry>
                            <entry>Zeitüberschreitung für Verbindungen (Sekunden)</entry>
                            <entry>integer</entry>
                            <entry>10</entry>
                        </row>

                        <row>
                            <entry>httpversion</entry>

                            <entry>
                                Version des <acronym>HTTP</acronym> Protokolls (normalerweise '1.1'
                                oder '1.0')
                            </entry>

                            <entry>string</entry>
                            <entry>'1.1'</entry>
                        </row>

                        <row>
                            <entry>adapter</entry>

                            <entry>
                                Zu verwendende Adapterklasse für die Verbindung (siehe
                                <link linkend="zend.http.client.adapters">diesen Abschnitt</link>)
                            </entry>

                            <entry>mixed</entry>
                            <entry>'Zend_Http_Client_Adapter_Socket'</entry>
                        </row>

                        <row>
                            <entry>keepalive</entry>

                            <entry>
                                Ob keep-alive Verbindungen mit dem Server aktiviert werden sollen.
                                Nützlich und kann die Performance verbessern, wenn mehrere
                                aufeinanderfolgende Anfragen an denselben Server ausgeführt werden.
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>FALSE</constant></entry>
                        </row>

                        <row>
                            <entry>storeresponse</entry>

                            <entry>
                                Ob die letzte Antwort für einen späteren Aufruf von
                                <methodname>getLastResponse()</methodname> gespeichert werden soll.
                                Wird sie auf <constant>FALSE</constant> gesetzt, gibt
                                <methodname>getLastResponse()</methodname> <constant>NULL</constant>
                                zurück.
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>TRUE</constant></entry>
                        </row>

                        <row>
                            <entry>encodecookies</entry>

                            <entry>
                                Ob der Cookie-Wert über urlencode oder urldecode übergeben werden
                                soll oder nicht. Dessen Aktivierung verhindert die Unterstützung
                                bei einigen Web-Servern. Dessen Deaktivierung limitiert den
                                Bereich der Werte, die Cookies enthalten können.
                            </entry>

                            <entry>boolean</entry>
                            <entry><constant>TRUE</constant></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>
    </sect2>

    <sect2 id="zend.http.client.basic-requests">
        <title>Durchführen von einfachen HTTP-Anfragen</title>

        <para>
            Das Durchführen von einfachen <acronym>HTTP</acronym>-Anfragen kann sehr leicht durch
            Verwendung der Methode request() gemacht werden und benötigt selten mehr als drei
            Codezeilen:

            <example id="zend.http.client.basic-requests.example-1">
                <title>Durchführen einer einfache GET-Anfrage</title>

                <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client('http://example.org');
$response = $client->request();
]]></programlisting>
            </example>

            Die Methode request() akzeptiert einen optionalen Parameter - die Anfragemethode.
            Diese kann <property>GET</property>, <property>POST</property>,
            <property>PUT</property>, <property>HEAD</property>, <property>DELETE</property>,
            <property>TRACE</property>, <property>OPTIONS</property> oder
            <property>CONNECT</property> sein, wie im <acronym>HTTP</acronym>-Protokoll definiert.

            <footnote>
                <para>
                    Siehe RFC 2616 - <ulink
                        url="http://www.w3.org/Protocols/rfc2616/rfc2616.html" />.
                </para>
            </footnote>.

            Der Bequemlichkeit halber sind alle als Klassenkonstanten definiert:
            Zend_Http_Client::GET, Zend_Http_Client::POST und so weiter.
        </para>

        <para>
            Wenn keine Methode angegeben worden ist, wird die durch den letzten Aufruf von
            <methodname>setMethod()</methodname> gesetzte Methode verwendet. Wenn
            <methodname>setMethod()</methodname> vorher nicht aufgerufen worden ist, wird als
            Standardmethode <constant>GET</constant> verwendet (siehe obiges Beispiel).

            <example id="zend.http.client.basic-requests.example-2">
                <title>Andere Anfragemethoden als GET verwenden</title>

                <programlisting language="php"><![CDATA[
// Durchführen einer POST Anfrage
$response = $client->request('POST');

// Ein weiterer Weg, eine POST Anfrage durchzuführen
$client->setMethod(Zend_Http_Client::POST);
$response = $client->request();
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.client.parameters">
        <title>Hinzufügen von GET und POST Parametern</title>

        <para>
            Das Hinzufügen von <constant>GET</constant>-Parametern zu einer <acronym>HTTP</acronym>-Anfrage
            ist recht einfach und kann entweder über die Angabe als Teil der URL oder durch
            Verwendung der Methode setParameterGet() erfolgen. Diese Methode benötigt den Namen des
            <constant>GET</constant>-Parameters als seinen ersten Parameter und den Wert des
            <constant>GET</constant>-Parameters als seinen zweiten Parameter. Zur Erleichterung
            akzeptiert die Methode setParameterGet() auch ein einzelnes assoziatives Array mit
            <constant>GET</constant>-Parameter als Name => Wert Variablen, was beim Setzen von
            mehreren <constant>GET</constant>-Parametern komfortabler sein kann.

            <example id="zend.http.client.parameters.example-1">
                <title>Setzen von GET-Parametern</title>

                <programlisting language="php"><![CDATA[
// Setzen eines GET-Parameters mit der Methode setParameterGet
$client->setParameterGet('knight', 'lancelot');

// Dies ist äquivalent zum Setzen der URL:
$client->setUri('http://example.com/index.php?knight=lancelot');

// Hinzufügen mehrerer Parameter durch einen Aufruf
$client->setParameterGet(array(
    'first_name'  => 'Bender',
    'middle_name' => 'Bending'
    'made_in'     => 'Mexico',
));
]]></programlisting>
            </example>
        </para>

        <para>
            Während <constant>GET</constant>-Parameter bei jeder Anfragemethode gesetzt werden
            können, können POST-Parameter nur im Hauptteil von POST-Anfragen versendet werden. Das
            Hinzufügen von POST-Parameter zu einer Anfrage ist sehr ähnlich wie das Hinzufügen von
            <constant>GET</constant>-Parametern and kann mit der Methode setParameterPost() gemacht
            werden, die vom Aufbau der Methode setParameterGet() ähnlich ist.

            <example id="zend.http.client.parameters.example-2">
                <title>Setzen von POST-Parametern</title>

                <programlisting language="php"><![CDATA[
// Setzen eines POST-Parameters
$client->setParameterPost('language', 'fr');

// Hinzufügen von mehreren POST-Parametern, eines davon mit mehreren Werten
$client->setParameterPost(array(
    'language'  => 'es',
    'country'   => 'ar',
    'selection' => array(45, 32, 80)
));
]]></programlisting>
            </example>

            Beim Senden einer POST-Anfrage ist zu beachten, dass man sowohl <constant>GET</constant>-
            als auch POST-Parameter setzen kann. Auf der anderen Seite wird durch das Setzen von
            POST-Parametern für andere Anfragen als POST kein Fehler ausgeworfen. Solange eine
            Anfrage keine POST-Anfrage ist, werden POST-Parameter einfach ignoriert.
        </para>
    </sect2>

    <sect2 id="zend.http.client.accessing_last">
        <title>Zugriff auf die letzte Anfrage und Antwort</title>

        <para>
            <classname>Zend_Http_Client</classname> verfügt über Methoden für den Zugriff auf die
            letzte gesendete Anfrage und die letzte empfangene Antwort des Client-Objekts.
            <classname>Zend_Http_Client->getLastRequest()</classname> hat keine Parameter und gibt
            die letzte <acronym>HTTP</acronym>-Anfrage als String zurück, die der Client gesendet
            hat. Auf die gleiche Art und Weise gibt
            <classname>Zend_Http_Client->getLastResponse()</classname> die letzte
            <acronym>HTTP</acronym>-Antwort als <link
                linkend="zend.http.response">Zend_Http_Response</link> Objekt zurück, die der Client
            empfangen hat.
        </para>
    </sect2>
</sect1>