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

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

    <sect2 id="zend.http.client.adapters.overview">
        <title>Présentation globale</title>

        <para>
            <classname>Zend_Http_Client</classname> accepte des objets adaptateurs. Ces objets
            ont la responsabilité de soutenir la connexion vers un serveur, à savoir écrire des
            requêtes et lire des réponses L'adaptateur peut donc être changé, et même écrit ou
            réécrit pour correspondre à vos besoins, sans avoir l'obligation de toucher à toute la
            classe dite "client". Vous vous connectez et manipulez votre connexion toujours de la
            même manière quelque soit l'adaptateur situé dessous.
        </para>

        <para>
            Actuellement, la classe cliente <classname>Zend_Http_Client</classname> est
            fournie avec quatre adaptateurs : <itemizedlist>
                    <listitem>
                        <para><classname>Zend_Http_Client_Adapter_Socket</classname> (défaut)</para>
                    </listitem>

                    <listitem>
                        <para><classname>Zend_Http_Client_Adapter_Proxy</classname></para>
                    </listitem>

                    <listitem>
                        <para><classname>Zend_Http_Client_Adapter_Curl</classname></para>
                    </listitem>

                    <listitem>
                        <para><classname>Zend_Http_Client_Adapter_Test</classname></para>
                    </listitem>
                </itemizedlist>
            </para>

        <para>
            L'objet Zend_Http_Client se voit spécifié un adaptateur via son constructeur avec
            le tableau d'options, à l'index 'adapter'. Fournissez alors une chaîne représentant la
            classe d'adaptateur à utiliser (par exemple 'Zend_Http_Client_Adapter_Socket'), ou un
            objet directement (par exemple <code> new Zend_Http_Client_Adapter_Test</code>). Vous
            pouvez de même passer un adaptateur plus tard, avec la méthode
            <classname>Zend_Http_Client-&gt;setConfig()</classname>.
        </para>
    </sect2>

    <sect2 id="zend.http.client.adapters.socket">
        <title>Adaptateur Socket</title>

        <para>
            L'adaptateur par défaut est Zend_Http_Client_Adapter_Socket. Il est basé sur les
            fonctions <acronym>PHP</acronym> <methodname>fsockopen()</methodname> et soeurs. Il ne nécessite donc aucune extension
            particulière ni option de compilation de <acronym>PHP</acronym>.
        </para>

        <para>
            L'adaptateur Socket peut être configuré avec des options, passées par
            <classname>Zend_Http_Client-&gt;setConfig()</classname> ou au constructeur du client.
            <table id="zend.http.client.adapter.socket.configuration.table">
                    <title>Zend_Http_Client_Adapter_Socket configuration</title>

                    <tgroup cols="4">
                        <thead>
                            <row>
                                <entry>Paramètre</entry>
                                <entry>Description</entry>
                                <entry>Types attendus</entry>
                                <entry>Valeur par défaut</entry>
                            </row>
                        </thead>

                        <tbody>
                            <row>
                                <entry>persistent</entry>
                                <entry>Utilise ou non les connexions <acronym>TCP</acronym> persistantes</entry>
                                <entry>booléen</entry>
                                <entry>false</entry>
                            </row>

                            <row>
                                <entry>ssltransport</entry>
                                <entry>Couche de transport <acronym>SSL</acronym> ('sslv2', 'tls')</entry>
                                <entry>chaîne</entry>
                                <entry>ssl</entry>
                            </row>

                            <row>
                                <entry>sslcert</entry>
                                <entry>Chemin vers le certificat <acronym>SSL</acronym> encodé <acronym>PEM</acronym></entry>
                                <entry>chaîne</entry>
                                <entry>null</entry>
                            </row>

                            <row>
                                <entry>sslpassphrase</entry>
                                <entry>Phrase de passe pour le fichier de certificat <acronym>SSL</acronym></entry>
                                <entry>chaîne</entry>
                                <entry>null</entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table> <note>
                    <title>Connexions <acronym>TCP</acronym> persistantes</title>

                <para>
                    L'utilisation de connexions <acronym>TCP</acronym> persistantes peut potentiellement
                    accélérer vos requêtes <acronym>HTTP</acronym> mais n'a, dans la plupart des cas, qu'un petit effet
                    positif et peut surcharger le serveur <acronym>HTTP</acronym> auquel vous êtes connecté.
                </para>

                <para>
                    Il est recommandé d'utiliser les connexions <acronym>TCP</acronym> persistantes seulement si
                    vous vous connectez au même serveur très fréquemment, et que vous êtes sûr que
                    le serveur est capable de gérer un nombre élevé de connections concurrentes.
                    Dans tous les cas vous êtes encouragés à tester l'effet des connections
                    persistantes à la fois sur l'accélération du client et sur la charge du serveur
                    avant d'activer cette option.
                </para>

                <para>
                    De plus, quand vous utilisez des connexions persistantes, il est
                    recommandé d'activer l'option "Keep-Alive" décrite dans <xref
                    linkend="zend.http.client.configuration" />, sinon les connexions persistantes
                    n'auront que peu ou pas d'effet.
                </para>
            </note> <note>
                <title>HTTPS SSL Paramètres de flux</title>

                <para>
                    <code>ssltransport, sslcert</code> and <code>sslpassphrase</code> sont
                    seulement appropriées lors de l'utilisation d'HTTPS.
                </para>

                <para>
                    Bien que les réglages par défaut du mode <acronym>SSL</acronym> fonctionneront pour la
                    plupart des applications, vous pourrez avoir besoin de les changer si le
                    serveur, auquel vous vous connectez, requière un paramétrage particulier du
                    client. Dans ce cas, vous devriez lire les sections sur la couche de transport
                    <acronym>SSL</acronym> et ses options à cette <ulink
                    url="http://www.php.net/manual/en/transports.php#transports.inet">adresse</ulink>.
                </para>
                </note>
            </para>

        <example id="zend.http.client.adapters.socket.example-1">
            <title>Changer la couche de transport HTTPS</title>

            <programlisting language="php"><![CDATA[
// Définit des paramètres de configuration
$config = array(
    'adapter'      => 'Zend_Http_Client_Adapter_Socket',
    'ssltransport' => 'tls'
);

// Instantie un objet client
$client = new Zend_Http_Client('https://www.example.com', $config);

// Cette requête sera envoyée vers une connexion sécurisée TLS
$response = $client->request();
]]></programlisting>
        </example>

        <para>
            Le résultat ci-dessus sera similaire à l'ouverture d'une connexion <acronym>TCP</acronym> avec la
            commande <acronym>PHP</acronym> suivante :
        </para>

        <para><methodname>fsockopen('tls://www.example.com', 443)</methodname></para>

        <sect3 id="zend.http.client.adapters.socket.streamcontext">
            <title>Customizing and accessing the Socket adapter stream context</title>
            <para>
                Starting from Zend Framework 1.9, <classname>Zend_Http_Client_Adapter_Socket</classname>
                provides direct access to the underlying <ulink url="http://php.net/manual/en/stream.contexts.php">stream context</ulink>
                used to connect to the remote server. This allows the user to pass
                specific options and parameters to the <acronym>TCP</acronym> stream, and to the <acronym>SSL</acronym> wrapper in
                case of <acronym>HTTPS</acronym> connections.
            </para>

            <para>
                You can access the stream context using the following methods of <classname>Zend_Http_Client_Adapter_Socket</classname>:
                <itemizedlist>
                    <listitem>
                        <para>
                            <firstterm><methodname>setStreamContext($context)</methodname></firstterm>
                            Sets the stream context to be used by the adapter. Can accept either
                            a stream context resource created using the
                            <ulink url="http://php.net/manual/en/function.stream-context-create.php"><methodname>stream_context_create()</methodname></ulink>
                            <acronym>PHP</acronym> function, or an array of stream context options, in the same format provided to this function.
                            Providing an array will create a new stream context using these options, and set it.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <firstterm><methodname>getStreamContext()</methodname></firstterm>
                            Get the stream context of the adapter. If no stream context was set,
                            will create a default stream context and return it. You can then set
                            or get the value of different context options using regular <acronym>PHP</acronym> stream
                            context functions.
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
            <example id="zend.http.client.adapters.socket.streamcontext.example-1">
            <title>Setting stream context options for the Socket adapter</title>
            <programlisting language="php"><![CDATA[
// Array of options
$options = array(
    'socket' => array(
        // Bind local socket side to a specific interface
        'bindto' => '10.1.2.3:50505'
    ),
    'ssl' => array(
        // Verify server side certificate,
        // do not accept invalid or self-signed SSL certificates
        'verify_peer' => true,
        'allow_self_signed' => false,

        // Capture the peer's certificate
        'capture_peer_cert' => true
    )
);

// Create an adapter object and attach it to the HTTP client
$adapter = new Zend_Http_Client_Adapter_Socket();
$client = new Zend_Http_Client();
$client->setAdapter($adapter);

// Method 1: pass the options array to setStreamContext()
$adapter->setStreamContext($options);

// Method 2: create a stream context and pass it to setStreamContext()
$context = stream_context_create($options);
$adapter->setStreamContext($context);

// Method 3: get the default stream context and set the options on it
$context = $adapter->getStreamContext();
stream_context_set_option($context, $options);

// Now, preform the request
$response = $client->request();

// If everything went well, you can now access the context again
$opts = stream_context_get_options($adapter->getStreamContext());
echo $opts['ssl']['peer_certificate'];
]]></programlisting>
        </example>

        <note>
            <para>
                Note that you must set any stream context options before using the adapter
                to preform actual requests. If no context is set before preforming <acronym>HTTP</acronym> requests
                with the Socket adapter, a default stream context will be created. This context
                resource could be accessed after preforming any requests using the
                <methodname>getStreamContext()</methodname> method.
            </para>
        </note>
        </sect3>
    </sect2>

    <sect2 id="zend.http.client.adapters.proxy">
        <title>Adaptateur Proxy</title>

        <para>
            L'adaptateur Zend_Http_Client_Adapter_Proxy est identique à celui par défaut,
            Socket, sauf que Proxy se connectera au serveur via un serveur Proxy (mandataire). Cette
            utilisation peut être rencontrée pour des raisons de performances ou de sécurité.
        </para>

        <para>
            En utilisant l'adaptateur Proxy, quelques paramètres de configuration seront
            nécessaires en plus du paramètre 'adapter' : <table
                    id="zend.http.client.adapters.proxy.table">
                    <title>Zend_Http_Client paramètres de configuration</title>

                    <tgroup cols="4">
                        <thead>
                            <row>
                                <entry>Paramètre</entry>
                                <entry>Description</entry>
                                <entry>Valeurs attendues</entry>
                                <entry>Valeur par défaut</entry>
                            </row>
                        </thead>

                        <tbody>
                            <row>
                                <entry>proxy_host</entry>
                                <entry>Adresse du serveur Proxy</entry>
                                <entry>chaîne</entry>
                                <entry>'proxy.myhost.com' ou '10.1.2.3'</entry>
                            </row>

                            <row>
                                <entry>proxy_port</entry>
                                <entry>Port du serveur Proxy</entry>
                                <entry>entier</entry>
                                <entry>8080 (défaut) ou 81</entry>
                            </row>

                            <row>
                                <entry>proxy_user</entry>
                                <entry>nom d'utilisateur pour le Proxy, si requis</entry>
                                <entry>chaîne</entry>
                                <entry>'shahar' ou '' pour aucun (défaut)</entry>
                            </row>

                            <row>
                                <entry>proxy_pass</entry>
                                <entry>Mot de passe du Proxy, si requis</entry>
                                <entry>chaîne</entry>
                                <entry>'secret' ou '' pour aucun (défaut)</entry>
                            </row>

                            <row>
                                <entry>proxy_auth</entry>
                                <entry>Type d'authentification <acronym>HTTP</acronym> du Proxy</entry>
                                <entry>chaîne</entry>
                                <entry>Zend_Http_Client::AUTH_BASIC (défaut)</entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
            </para>

        <para>
            <code>proxy_host</code> devrait toujours être fourni. Si ça n'est pas le cas,
            alors le client retournera sur une connexion Socket par défaut. <code>proxy_port</code>
            est par défaut à "8080".
        </para>

        <para>
            <code>proxy_user</code> et <code>proxy_pass</code> ne sont requis que si le
            serveur Proxy demande une authentification. Si vous remplissez ces options, alors un
            champ d'en-tête <acronym>HTTP</acronym> "Proxy-Authentication" sera ajouté à vos requêtes, via votre
            client.
        </para>

        <para>
            <code>proxy_auth</code> définit le type d'authentification à utiliser, si le
            serveur Proxy demande une authentification. Actuellement, seule la méthode "basic"
            (<classname>Zend_Http_Client::AUTH_BASIC</classname>) est supportée.
        </para>

        <example id="zend.http.client.adapters.proxy.example-1">
            <title>Utiliser Zend_Http_Client derrière un serveur Proxy</title>

            <programlisting language="php"><![CDATA[
// Paramètres de configuration
$config = array(
    'adapter'    => 'Zend_Http_Client_Adapter_Proxy',
    'proxy_host' => 'proxy.int.zend.com',
    'proxy_port' => 8000,
    'proxy_user' => 'shahar.e',
    'proxy_pass' => 'bananashaped'
);

// Crée l'objet client
$client = new Zend_Http_Client('http://www.example.com', $config);

// utilisez l'objet client ici ...
]]></programlisting>
        </example>

        <para>
            Comme déjà dit, si proxy_host n'est pas rempli ou défini en tant que chaîne vide,
            alors le client utilisera l'adaptateur Socket par défaut. Ceci est utile si le proxy est
            utilisé optionnellement, ou par intermittence.
        </para>

        <note>
            <para>
                Since the proxy adapter inherits from <classname>Zend_Http_Client_Adapter_Socket</classname>,
                you can use the stream context access method (see <xref linkend="zend.http.client.adapters.socket.streamcontext" />)
                to set stream context options on Proxy connections as demonstrated above.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.http.client.adapters.curl">
        <title>The cURL Adapter</title>
        <para>
            cURL is a standard <acronym>HTTP</acronym> client library that is distributed with many
            operating systems and can be used in <acronym>PHP</acronym> via the cURL extension. It
            offers functionality for many special cases which can occur for a <acronym>HTTP</acronym>
            client and make it a perfect choice for a <acronym>HTTP</acronym> adapter. It supports
            secure connections, proxy, all sorts of authentication mechanisms
            and shines in applications that move large files around between servers.
        </para>

        <example id="zend.http.client.adapters.curl.example-1">
            <title>Setting cURL options</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>
            By default the cURL adapter is configured to behave exactly like
            the Socket Adapter and it also accepts the same configuration parameters
            as the Socket and Proxy adapters. You can also change the cURL options by either specifying
            the 'curloptions' key in the constructor of the adapter or by calling
            <methodname>setCurlOption($name, $value)</methodname>. The <varname>$name</varname> key
            corresponds to the CURL_* constants of the cURL extension. You can
            get access to the Curl handle by calling <code>$adapter->getHandle();</code>
        </para>

        <example id="zend.http.client.adapters.curl.example-2">
            <title>Transfering Files by Handle</title>

            <para>
                You can use cURL to transfer very large files over <acronym>HTTP</acronym> by filehandle.
            </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.test">
        <title>Adaptateur Test</title>

        <para>
            Il est quelque fois difficile de tester une application qui a besoin d'une
            connexion <acronym>HTTP</acronym>. Par exemple, une application qui est en charge de lire un flux <acronym>RSS</acronym> aura
            besoin d'une connexion, qui n'est pas tout le temps disponible.
        </para>

        <para>
            C'est pour cette raison que l'adaptateur
            <classname>Zend_Http_Client_Adapter_Test</classname> est présent. Vous pouvez de cette
            manière écrire vos applications, et lors de la phase de tests, passer votre connexion
            sur l'adaptateur Test (objet mock).
        </para>

        <para>
            La classe <classname>Zend_Http_Client_Adapter_Test</classname> possède une méthode
            supplémentaire, <methodname>setResponse()</methodname>. Elle prend en paramètre un objet
            <classname>Zend_Http_Response</classname> ou une chaîne. Une fois cet objet de réponse
            déterminé, l'adaptateur de Test retournera toujours cette réponse, sans effectuer de
            réelle requête <acronym>HTTP</acronym>.
        </para>

        <example id="zend.http.client.adapters.test.example-1">
            <title>Tester avec un objet de réponse HTTP unique</title>

            <programlisting language="php"><![CDATA[
// Création de l'adatateur et de l'objet client :
$adapter = new Zend_Http_Client_Adapter_Test();
$client = new Zend_Http_Client('http://www.example.com', array(
    'adapter' => $adapter
));

// Passage de l'objet de réponse
$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>' .
    // etc....
    '</rss>');

$response = $client->request('GET');
// ... continuez à parser $response...
]]></programlisting>
        </example>

        <para>
            L'exemple ci dessus montre comment préconfigurer la réponse qui sera retournée
            lors d'une requête de votre objet client. Ainsi lors des tests, votre application
            continuera de se comporter normalement, elle aura tout simplement été trompée (mock).
            Aucune connexion <acronym>HTTP</acronym> n'est dans ce cas là nécessaire.
        </para>

        <para>
            Quelques fois, plusieurs transactions <acronym>HTTP</acronym> peuvent être nécessaires. Une réponse
            peut demander une redirection, vers une autre. Dans ce cas, utiliser
            <methodname>setResponse()</methodname> toute seule n'est pas possible car il ne sera pas possible de
            spécifier les réponses suivantes, nécessaires alors à l'application.
        </para>

        <example id="zend.http.client.adapters.test.example-2">
            <title>Tester avec plusieurs réponses HTTP</title>

            <programlisting language="php"><![CDATA[
// Création des objets adaptateur, et client
$adapter = new Zend_Http_Client_Adapter_Test();
$client = new Zend_Http_Client('http://www.example.com', array(
    'adapter' => $adapter
));

// Configuration de la première réponse attendue
$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>');

// Configuration des réponses successives
$adapter->addResponse(
    "HTTP/1.1 200 OK"         . "\r\n" .
    "Content-Type: text/html" . "\r\n" .
                                "\r\n" .
    '<html>' .
    '  <head><title>My Pet Store Home Page</title></head>' .
    '  <body><p>...</p></body>' .
    '</html>');

// l'objet $client est prêt à être testé
// son comportement est déja configuré
]]></programlisting>
        </example>

        <para>
            La méthode <methodname>setResponse()</methodname> détruit toutes les réponses dans le buffer
            de <classname>Zend_Http_Client_Adapter_Test</classname> et définit la première réponse
            qui sera retournée. La méthode <methodname>addResponse()</methodname> définit les réponses
            suivantes.
        </para>

        <para>Les réponses seront rejouées dans leur ordre d'ajout.</para>

        <para>
            Dans l'exemple ci-dessus, l'adaptateur est configuré pour un scénario de test de
            redirections 302. En fonction de votre application, le suivi d'une redirection peut être
            ou non désiré. Dans notre exemple, nous nous attendons à ce que la redirection soit
            suivie et nous configurons notre adaptateur de tests pour ceci. La réponse de
            redirection originelle (302) est définie avec la méthode <methodname>setResponse()</methodname>,
            quant à la réponse non redirigeante (200) suivante, elles est définie avec la méthode
            <methodname>addResponse()</methodname>. Lorsque votre objet client est configuré, vous pouvez
            l'injecter dans votre application à tester, et voir le résultat et les
            comportements.
        </para>
    </sect2>

    <sect2 id="zend.http.client.adapters.extending">
        <title>Créer vos propres adaptateurs de connexion</title>

        <para>
            Vous pouvez créer vos propres adaptateurs, si vous avez un besoin spécial à
            utiliser. Par exemple, des possibilités de cache, ou des sockets persistantes.
        </para>

        <para>
            Pour ceci, votre classe d'adaptateur doit implémenter l'interface
            <classname>Zend_Http_Client_Adapter_Interface</classname>. L'exemple suivant montre un
            squelette de classe. Toutes les méthodes publiques, ici, sont indispensables à la
            classe, elles sont issues de l'interface :
        </para>

        <example id="zend.http.client.adapters.extending.example-1">
            <title>Création de votre propre adaptateur de connexion</title>

            <programlisting language="php"><![CDATA[
class MyApp_Http_Client_Adapter_BananaProtocol
    implements Zend_Http_Client_Adapter_Interface
{
    /**
     * Définit le tableau de configuration pour cet adaptateur
     *
     * @param array $config
     */
    public function setConfig($config = array())
    {
        // Ceci change rarement, vous devriez copier l'implémentation
        // présente dans Zend_Http_Client_Adapter_Socket.
    }

    /**
     * Connecte à une serveur distant
     *
     * @param string  $host
     * @param int     $port
     * @param boolean $secure
     */
    public function connect($host, $port = 80, $secure = false)
    {
        // Etablit la connexion au serveur
    }

    /**
     * Envoie une requête au serveur
     *
     * @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 = '')
    {
        // Envoie la requête au serveur distant. Cette fonction devrait
        // retourner la requête complète (en-tête et corps) as a string
    }

    /**
     * Lit la réponse du serveur
     *
     * @return string
     */
    public function read()
    {
        // Lit la réponse du serveur distant, et la retourne sous forme
        // de chaine de caractères
    }

    /**
     * Ferme la connexion avec le serveur
     *
     */
    public function close()
    {
        // Ferme la connexion, appelée en dernière.
    }
}

// Maintenant, vous pouvez utiliser cet adaptateur :
$client = new Zend_Http_Client(array(
    'adapter' => 'MyApp_Http_Client_Adapter_BananaProtocol'
));
]]></programlisting>
        </example>
    </sect2>
</sect1>