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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15103 -->
<!-- Reviewed: no -->
<sect1 id="zend.http.client.adapters">
    <title>Zend_Http_Client - Verbindungsadapter</title>

    <sect2 id="zend.http.client.adapters.overview">
        <title>Verbindungsadapter</title>
        <para>
            Zend_Http_Client basiert auf einem Design mit Verbindungsadaptern. Der
            Verbindungsadapter ist das Objekt, welches für die Ausführung der aktuellen Verbindung
            zum Server sowie für das Schreiben der Anfragen und Lesen von Antworten verantwortlich ist.
            Dieser Verbindungsadapter kann ersetzt werden und man kann den Standard
            Verbindungsadapter durch seinen eigenen Adapter erweitern, um ihn mit dem selben
            Interface auf seine eigenen Bedürfnisse anzupassen, ohne dass man die gesamte HTTP
            Client Klasse erweitern oder ersetzen muss.
        </para>
        <para>
            Derzeit stellt die Zend_Http_Client Klasse zwei eingebaute Verbindungsadapter bereit:
            <itemizedlist>
                <listitem>
                    <para>
                        <classname>Zend_Http_Client_Adapter_Socket</classname> (Standard)
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Http_Client_Adapter_Proxy</classname>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Http_Client_Adapter_Test</classname>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Http_Client_Adapter_Curl</classname>
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            Der Verbindungsadapter für das Zend_Http_Client Objekt wird durch Verwendung der
            'adapter' Konfigurationsoption gesetzt. Beim Instanzieren des Client Objektes kann man
            die 'adapter' Konfigurationsoption setzen mit einem String, der den Adapternamen (z.B.
            'Zend_Http_Client_Adapter_Socket') enthält, oder mit eine Variable, die ein
            Adapterobjekt (z.B. <code>new Zend_Http_Client_Adapter_Test</code>) enthält. Man kann
            den Adapter auch danach setzen, indem man die Zend_Http_Client->setConfig() Methode
            verwendet.
        </para>
    </sect2>

    <sect2 id="zend.http.client.adapters.socket">
        <title>Der Socket Adapter</title>
        <para>
            Der Standard-Adapter von Zend_Http_Client ist der Zend_Http_Client_Adapter_Socket. Dieser
            wird benutzt, wenn kein anderer angegeben wird. Der Socket Adapter benutzt die native
            PHP Funktion fsockopen(), um die Verbindung aufzubauen, dafür werden keine besonderen
            PHP-Extensions oder Einstellungen benötigt.
        </para>
        <para>
            Der Socket Adapter erlaubt verschiedene zusätzliche Konfigurations Optionen die gesetzt werden
            können durch Verwendung von <classname>Zend_Http_Client->setConfig()</classname> oder deren Übergabe an
            den Konstruktor des Clients.
            <table id="zend.http.client.adapter.socket.configuration.table">
                <title>Zend_Http_Client_Adapter_Socket Konfigurations Parameter</title>
                <tgroup cols="4">
                    <thead>
                        <row>
                            <entry>Parameter</entry>
                            <entry>Beschreibung</entry>
                            <entry>Erwarteter Typ</entry>
                            <entry>Standardwert</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>persistent</entry>
                            <entry>Ob eine persistente TCP Verbindung verwendet werden soll oder nicht</entry>
                            <entry>boolean</entry>
                            <entry>false</entry>
                        </row>
                        <row>
                            <entry>ssltransport</entry>
                            <entry>SSL Transport Layer (eg. 'sslv2', 'tls')</entry>
                            <entry>string</entry>
                            <entry>ssl</entry>
                        </row>
                        <row>
                            <entry>sslcert</entry>
                            <entry>Pfad zu einem PEM verschlüsselten SSL Zertifikat</entry>
                            <entry>string</entry>
                            <entry>null</entry>
                        </row>
                        <row>
                            <entry>sslpassphrase</entry>
                            <entry>Die PassPhrase für die SSL zertifizierte Datei</entry>
                            <entry>string</entry>
                            <entry>null</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <note>
                <title>Persistente TCP Verbindungen</title>
                <para>
                    Die Verwendung persistenter TCP Verbindungen kann HTTP Anfragen potentiell schneller
                    machen - aber in den meisten Fällen, wird es nur einen kleinen positiven Effekt haben
                    und könnte den HTTP Server überladen zu dem man sich verbindet.
                </para>
                <para>
                    Es wird empfohlen persistente TCP Verbindungen nur dann zu verwenden wenn man sich
                    zu dem gleichen Server sehr oft verbindet, und man sicher ist das der Server eine
                    große Anzahl an gleichzeitigen Verbindungen behandeln kann. In jedem Fall wird
                    empfohlen das der Effekt von persistenten Verbindungen auf beiden, der Geschwindigkeit
                    des Clients und dem Serverload gemessen wird bevor diese Option verwendet wird.
                </para>
                <para>
                    Zusätzlich, wenn persistente Verbindungen verwendet werden, sollte man Keep-Alive
                    HTTP Anfragen aktivieren wie in <xref linkend="zend.http.client.configuration" />
                    beschrieben - andernfalls werden persistente Verbindungen nur wenig oder gar keinen
                    Effekt haben.
                </para>
            </note>

            <note>
                <title>HTTPS SSL Stream Parameter</title>
                <para>
                    <code>ssltransport, sslcert</code> und <code>sslpassphrase</code> sind nur relevant
                    wenn HTTPS für die Verbindung verwendet wird.
                </para>
                <para>
                    Wärend die Standard SSL Einstellungen für die meisten Anwendungen funktionieren, kann
                    es notwendig sein diese zu Ändern wenn der Server zu dem man sich verbindet ein
                    spezielles Client Setup benötigt. Wenn dem so ist, sollte man das Kapitel über SSL
                    Transport Layer und Optionen lesen das
                    <ulink url="http://www.php.net/manual/en/transports.php#transports.inet">hier</ulink>
                    zu finden ist.
                </para>
            </note>
        </para>
        <example id="zend.http.client.adapters.socket.example-1">
            <title>Den Stream-Typen für eine HTTPS Verbindung einstellen</title>
            <programlisting role="php"><![CDATA[
// Konfigurationsparameter setzen
$config = array(
    'adapter'      => 'Zend_Http_Client_Adapter_Socket',
    'ssltransport' => 'tls'
);

// Client-Instanz erzeugen
$client = new Zend_Http_Client('https://www.example.com', $config);

// Jetzt wird der Request über eine verschlüsselte Verbindung verschickt
$response = $client->request();
]]>
            </programlisting>
        </example>
        <para>
            Ein ähnliches Ergebnis erzielt man mit folgendem Code:
        </para>
        <para>
            <code>fsockopen('tls://www.example.com', 443)</code>
        </para>
    </sect2>

    <sect2 id="zend.http.client.adapters.proxy">
        <title>Der Proxy Adapter</title>
        <para>
                        Der Proxy Adapter Zend_Http_Client_Adapter_Proxy verhält sich wie der
                        standard Zend_Http_Client_Adapter_Socket, mit dem Unterschied, dass
                        die Verbindung über einen Proxy-Server aufgebaut wird.
        </para>

        <para>
                Der Proxy Adapter benötigt zusätzliche Konfigurationsvariablen, die
                nachfolgend gelistet sind.
            <table id="zend.http.client.adapters.proxy.table">
                <title>Zend_Http_Client Konfigurationsparameter</title>
                <tgroup cols="4">
                    <thead>
                        <row>
                            <entry>Parameter</entry>
                            <entry>Beschreibung</entry>
                            <entry>Datentyp</entry>
                            <entry>Beispielwert</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>proxy_host</entry>
                            <entry>Proxy-Server-Adresse</entry>
                            <entry>string</entry>
                            <entry>'proxy.myhost.com' oder '10.1.2.3'</entry>
                        </row>
                        <row>
                            <entry>proxy_port</entry>
                            <entry>TCP Port des Proxy-Servers</entry>
                            <entry>integer</entry>
                            <entry>8080 (Standardwert) oder 81</entry>
                        </row>
                        <row>
                            <entry>proxy_user</entry>
                            <entry>Benutzername für die Proxynutzung, falls nötig</entry>
                            <entry>string</entry>
                            <entry>'wulli' oder '' für keinen Namen (Standardwert)</entry>
                        </row>
                        <row>
                            <entry>proxy_pass</entry>
                            <entry>Passwort für die Proxynutzung, falls nötig</entry>
                            <entry>string</entry>
                            <entry>'geheim' oder '' für kein Passwort (Standardwert)</entry>
                        </row>
                        <row>
                            <entry>proxy_auth</entry>
                            <entry>Proxy HTTP Authentifizierungs-Typ</entry>
                            <entry>string</entry>
                            <entry>Zend_Http_Client::AUTH_BASIC (Standardwert)</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>
        <para>
                        proxy_host muss immer gesetzt werden, ansonsten wird der Proxy-Adapter
                        auf Zend_Http_Client_Adapter_Socket zurückgreifen und keinen Proxy Server
                        benutzen.
                        Wird kein Prot mit übergeben, so versucht der Proxy-Adapter sich auf den
                        Standardport '8080' zu verbinden.
        </para>
        <para>
                        proxy_user und proxy_pass werden nur dann benötigt, wenn der Proxy-Server
                        tatsächlich eine Authentifizierung erwartet. Werden diese Parameter mit
                        übergeben, setzt der Proxy-Adapter zusätzlich den 'Proxy-Authentication'
                        Header bei Anfragen.
                        Wird keine Authentifizierung benötigt, sollten die beiden Parameter weggelassen werden.
        </para>
        <para>
                        proxy_auth setzt den Authentifizierungs-Typ. Dies ist nur nötig, wenn der
                        Proxy-Server eine Authentifizierung erwartet.
                        Mögliche Werte entsprechen denen der Zend_Http_Client::setAuth() Methode.
                        Zur Zeit wird nur die BASIC-Authentifizierung ((Zend_Http_Client::AUTH_BASIC)
                        unterstützt.
        </para>
        <example id="zend.http.client.adapters.proxy.example-1">
            <title>Zend_Http_Client hinter einem Proxy-Server nutzen</title>
            <programlisting role="php"><![CDATA[
// Konfigurationsparameter setzen
$config = array(
    'adapter'    => 'Zend_Http_Client_Adapter_Proxy',
    'proxy_host' => 'proxy.int.zend.com',
     'proxy_port' => 8000,
    'proxy_user' => 'shahar.e',
    'proxy_pass' => 'bananashaped'
);

// Client-Objekt instanziieren
$client = new Zend_Http_Client('http://www.example.com', $config);

// $client kann jetzt wie gewohnt benutzt werden
]]>
            </programlisting>
        </example>
        <para>
                        Wie vorher erwähnt, nutzt der Proxy-Adapter eine einfache Socket-Verbindung,
                        wenn proxy_host nicht gesetzt oder leer gelassen wurde. Dies ermöglicht
                        die optionale Nutzung eines Proxy-Servers, abhängig von dem proxy_host
                        Parameter.
        </para>
    </sect2>

    <sect2 id="zend.http.client.adapters.test">
        <title>Der Test Adapter</title>
        <para>
            Manchmal ist es sehr schwer Code tu testen, der von HTTP Verbindungen abhängig ist.
            Zum Beispiel verlangt das Testen einer Applikation, die einen RSS Feed von einem fremden
            Server anfordert, eine Netzwerkverbindung, die nicht immer verfügbar ist.
        </para>
        <para>
            Aus diesem Grund wird der Zend_Http_Client_Adapter_Test Adapter bereit gestellt. Man
            kann seine eigenen Applikationen schreiben, um Zend_Http_Client zu verwenden, und nur
            zu Testzwecken, z.B. in der Unit Test Suite, den Standardadapter durch den Testadapter
            (ein Mock Objekt) austauschen, um Tests ohne direkte Serverbindungen auszuführen.
        </para>
        <para>
            Der Zend_Http_Client_Adapter_Test Adapter stellt die zusätzliche Methode setResponse()
            bereit. Diese Methode nimmt einen Parameter entgegen, der eine HTTP Antwort entweder als
            Text oder als Zend_Http_Response Objekt repräsentiert. Einmal eingerichtet, wird der
            Testadapter immer diese Antwort zurückgeben, ohne tatsächlich eine HTTP Anfrage
            auszuführen.
        </para>
        <example id="zend.http.client.adapters.test.example-1">
            <title>Testen gegen einen einfachen HTTP Response Stumpf</title>
            <programlisting role="php"><![CDATA[
// Instanziere einen neuen Adapter und Client
$adapter = new Zend_Http_Client_Adapter_Test();
$client = new Zend_Http_Client('http://www.example.com', array(
    'adapter' => $adapter
));

// Setze die erwartete Antwort
$adapter->setResponse(
    "HTTP/1.1 200 OK"        . "\r\n" .
    "Content-type: text/xml" . "\r\n" .
                               "\r\n" .
    '<?xml version="1.0" encoding="UTF-8"?>' .
    '<rss version="2.0" ' .
    '     xmlns:content="http://purl.org/rss/1.0/modules/content/"' .
    '     xmlns:wfw="http://wellformedweb.org/CommentAPI/"' .
    '     xmlns:dc="http://purl.org/dc/elements/1.1/">' .
    '  <channel>' .
    '    <title>Premature Optimization</title>' .
    // und so weiter...
    '</rss>');

$response = $client->request('GET');
// .. setze die Verarbeitung von $response fort...
]]>
            </programlisting>
        </example>
        <para>
            Das obere Beispiel zeigt, wie man einen HTTP Client voreinstellen kann, damit er die
            benötigte Antwort zurückgibt. Danach kann man mit den Testen des eigenen Codes weiter
            machen, ohne von einer Netzwerkverbindung, der Serverantwort, etc. abhängig zu sein. In
            diesem Fall würde der Test mit der Prüfung fortfahren, wie die Applikation das XML aus
            der Antwort verarbeitet..
        </para>
        <para>
                        Manchmal erfordert ein einziger Methoden-Aufruf mehrere HTTP-Übertragungen.
                        Um mehrere HTTP-Antworten zu erstellen, müssen mit setResponse() die erste
                        und mit addResponse() die nachfolgenden Antworten gesetzt werden.
        </para>
        <example id="zend.http.client.adapters.test.example-2">
            <title>Test mit mehreren HTTP-Antworten</title>
            <programlisting role="php"><![CDATA[
// Instanzen vom Adapter und Client erzeugen
$adapter = new Zend_Http_Client_Adapter_Test();
$client = new Zend_Http_Client('http://www.example.com', array(
    'adapter' => $adapter
));

// mit setResponse() die erste Antwort setzen
$adapter->setResponse(
    "HTTP/1.1 302 Found"      . "\r\n" .
    "Location: /"             . "\r\n" .
    "Content-Type: text/html" . "\r\n" .
                                "\r\n" .
    '<html>' .
    '  <head><title>Moved</title></head>' .
    '  <body><p>This page has moved.</p></body>' .
    '</html>');

// mit addResponse() nachfolgende Antworten setzen
$adapter->addResponse(
    "HTTP/1.1 200 OK"         . "\r\n" .
    "Content-Type: text/html" . "\r\n" .
                                    "\r\n" .
    '<html>' .
    '  <head><title>Meine Haustierseite...</title></head>' .
    '  <body><p>...</p></body>' .
    '</html>');

// Das $client Objekt kann jetzt zu testzwecken herangezogen werden,
// indem es wie ein normales Client-Objekt benutzt wird.
]]>
            </programlisting>
        </example>

        <para>
            Die HTTP-Antworten werden in der Reihenfolge zurückgegeben,
            in der sie angelegt worden sind. Gibt es mehr Anfragen als
            Antworten, so wird wieder bei der ersten Antwort angefangen.
        </para>
        <para>
            Das oben angeführte Beispiel kann dazu benutzt werden, um die Reaktion
            der eigenen Anwendung auf einen 302 Redirect (Weiterleitung) zu testen.
            Abhängig  von Ihrer Anwendung, kann es gewollt oder nicht gewollt sein,
            dass dem Redirect gefolgt wird.
        </para>
    </sect2>

    <sect2 id="zend.http.client.adapters.curl">
        <title>Der cURL Adapter</title>
        <para>
            cURL ist eine Standard HTTP Client Bibliothek die mit vielen Betriebssystemen
            ausgeliefert wird, und kann in PHP über die cURL Erweiterung verwendet werden.
            Sie bietet Funktionalitäten für viele spezielle Fälle die für einen HTTP Client
            auftreten können und machen sie zu einer perfekten Wahl für einen HTTP Adapter.
            Sie unterstützt sichere Verbindungen, Proxies, alle Arten von Authentifizierungs-
            mechanismen und glänzt in Anwendungen die große Dateien zwischen Servern bewegen
            müssen.
        </para>

        <example id="zend.http.client.adapters.curl.example-1">
            <title>Setzen von cURL Optionen</title>
            <programlisting role="php"><![CDATA[
$config = array(
    'adapter'   => 'Zend_Http_Client_Adapter_Curl',
    'curloptions' => array(CURLOPT_FOLLOWLOCATION => true),
);
$client = new Zend_Http_Client($uri, $config);
]]>
            </programlisting>
        </example>

        <para>
            Standardmäßig ist der cURL Adapter so konfiguriert das er sich genauso wie der
            Socket Adapter verhält. Man kann die cURL Optionen entweder durch den
            'curloptions' Schlüssel im Konstruktor des Adapters, oder durch den Aufruf von
            <code>setCurlOption($name, $value)</code>, verändern. Der <code>$name</code>
            Schlüssel entspricht den CURL_* Konstanten der cURL Erweiterung.
        </para>

        <example id="zend.http.client.adapters.curl.example-2">
            <title>Dateien von Hand übertragen</title>

            <para>
                Man kan cURL verwenden um große Dateien über HTTP durch einen Dateihandle zu
                übertragen.
            </para>

            <programlisting role="php"><![CDATA[
$putFileSize   = filesize("filepath");
$putFileHandle = fopen("filepath", "r");

$adapter = new Zend_Http_Client_Adapter_Curl();
$client = new Zend_Http_Client();
$client->setAdapter($adapter);
$adapter->setConfig(array(
    'curloptions' => array(
        CURLOPT_INFILE => $putFileHandle,
        CURLOPT_INFILESIZE => $putFileSize
    )
));
$client->request("PUT");
]]>
            </programlisting>
        </example>
    </sect2>

    <sect2 id="zend.http.client.adapters.extending">
        <title>Einen eigenen Adapter erstellen</title>
        <para>
            Es ist möglich eigene Verbindungs-Adapter zu schreiben, die spezielle
            Bedürfnisse, wie persistente Sockets oder gecachte Verbindungen, abdecken.
            Diese können dann, wie gewohnt mit dem Zend_Http_Client benutzt werden.
        </para>
        <para>
                        Um einen neuen Adapter zu erstellen, muss eine neue Klasse angelegt werden,
                        die das Zend_Http_Client_Adapter_Interface implementiert. Nachfolgend
                        finden Sie ein Gerüst für einen neuen Adapter. Die public-Methoden müssen
                        unbedingt implementiert werden.
        </para>
        <example id="zend.http.client.adapters.extending.example-1">
            <title>Gerüst für einen eigenen Verbindungs-Adapter</title>
            <programlisting role="php"><![CDATA[
class MyApp_Http_Client_Adapter_BananaProtocol
    implements Zend_Http_Client_Adapter_Interface
{
    /**
     * Konfigurationsarray für den Adapter
     *
     * @param array $config
     */
    public function setConfig($config = array())
    {
        // in den meisten Fällen kann die Implementierung von
        // Zend_Http_Client_Adapter_Socket eins zu eins übernommen werden
    }

    /**
     * Zum Server verbinden
     *
     * @param string  $host
     * @param int     $port
     * @param boolean $secure
     */
    public function connect($host, $port = 80, $secure = false)
    {
        // Verbindung zum Server herstellen
    }

    /**
     * Anfrage / Request an den Server stellen
     *
     * @param string        $method
     * @param Zend_Uri_Http $url
     * @param string        $http_ver
     * @param array         $headers
     * @param string        $body
     * @return string Request as text
     */
    public function write($method,
                          $url,
                          $http_ver = '1.1',
                          $headers = array(),
                          $body = '')
    {
        // Anfrage stellen
        // Diese Methode muss die komplette Antwort zurückliefern,
        // inklusive aller Header
    }

    /**
     * Antwort des Servers auslesen
     *
     * @return string
     */
    public function read()
    {
        // Antwort des Servers lesen und als String zurückgeben
    }

    /**
     * Verbindung zum Server beenden
     *
     */
    public function close()
    {
        // Verbindung beenden - wird zum Schluss aufgerufen
    }
}

// Jetzt kann der Adapter benutzt werden:
$client = new Zend_Http_Client(array(
    'adapter' => 'MyApp_Http_Client_Adapter_BananaProtocol'
));
]]>
            </programlisting>
        </example>
    </sect2>
</sect1>