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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 16501 -->
<!-- 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 vier 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 language="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 language="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 language="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 language="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 language="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 und er akzeptiert auch die gleichen Konfigurationsparameter wie
            die Socket und Proxy Adapter. 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. Man kann auf den
            CURL Handler durch den Aufruf von <code>$adapter->getHandle();</code> Zugriff erhalten.
        </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 language="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 language="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>