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

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

    <para>
        <classname>Zend_Http_Client</classname> fournit une interface qui permet d'utiliser le
        protocole <acronym>HTTP</acronym> (Hyper-Text Transfer Protocol). <classname>Zend_Http_Client</classname>
        supporte les fonctionnalités de base d'un client <acronym>HTTP</acronym>, ainsi que des fonctionnalités plus
        avancées, comme l'authentification ou l'upload de fichiers. Toutes les requêtes retournent
        un objet Zend_Http_Response, avec lequel on pourra accéder au corps ou aux en-têtes de la
        réponse <acronym>HTTP</acronym> (voyez <xref linkend="zend.http.response" />).
    </para>

    <sect2 id="zend.http.client.introduction">
        <title>Utilisation de Zend_Http_Client</title>

        <para>
            Le constructeur de classe accepte deux paramètres : l'URI (ou un objet
            <code><classname>Zend_Uri_Http</classname></code>), et un tableau ou un objet Zend_Config
            d'options de configuration. Ils peuvent aussi être définis avec des méthodes plus tard :
            <methodname>setUri()</methodname> et <methodname>setConfig()</methodname>.
            <example id="zend.http.client.introduction.example-1">
                    <title>Instanciation d'un objet Zend_Http_Client</title>

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

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

// You can also use a Zend_Config object to set the client's configuration
$config = new Zend_Config_Ini('httpclient.ini, 'secure');
$client->setConfig($config);
]]></programlisting>
                </example>
            </para>

        <note>
            <para>
                <classname>Zend_Http_Client</classname> utilise
                <classname>Zend_Uri_Http</classname> pour valider les <acronym>URL</acronym>s. Ce qui veut dire que
                certains caractères comme les pipes ("|") ou le symbole "^" ne seront pas acceptés
                par défaut dans les <acronym>URL</acronym>s. Ceci peut être modifié par le réglage de l'option
                "allow_unwise" de <classname>Zend_Uri</classname> à <constant>TRUE</constant>. Voir <xref
                linkend="zend.uri.validation.allowunwise" /> pour de plus amples
                informations.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.http.client.configuration">
        <title>Les paramètres de configuration</title>

        <para>
            Le constructeur et <methodname>setConfig()</methodname> acceptent un tableau associatif de
            paramètre de configuration, ou un objet Zend_Config. Fixer ces paramètres est optionnel,
            ils ont tous une valeur par défaut.
                <table id="zend.http.client.configuration.table">
                    <title>Zend_Http_Client : paramètres de configuration</title>

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

                        <tbody>
                            <row>
                                <entry>maxredirects</entry>
                                <entry>Nombre maximum de redirections à suivre (0 = aucune)</entry>
                                <entry>entier</entry>
                                <entry>5</entry>
                            </row>

                            <row>
                                <entry>strict</entry>
                                <entry>Validation faite ou non sur les noms d'en-têtes. Si à
                                <constant>FALSE</constant>, des fonctions de validation n'interviendront
                                pas. Habituellement ceci ne devrait pas être changé</entry>
                                <entry>booléen</entry>
                                <entry><constant>TRUE</constant></entry>
                            </row>

                            <row>
                                <entry>strictredirects</entry>
                                <entry>Est ce que le client doit suivre strictement les redirections
                                selon la <constant>RFC2616</constant> ? (voyez <xref
                                linkend="zend.http.client.redirections" />)</entry>
                                <entry>booléen</entry>
                                <entry><constant>FALSE</constant></entry>
                            </row>

                            <row>
                                <entry>useragent</entry>
                                <entry>La chaîne User Agent du client (envoyée en en-tête de
                                requête)</entry>
                                <entry>chaîne</entry>
                                <entry>'Zend_Http_Client'</entry>
                            </row>

                            <row>
                                <entry>timeout</entry>
                                <entry>Connexion timeout (secondes)</entry>
                                <entry>entier</entry>
                                <entry>10</entry>
                            </row>

                            <row>
                                <entry>httpversion</entry>
                                <entry>Version du protocole <acronym>HTTP</acronym> à utiliser ('1.1', '1.0' ou
                                '0.9')</entry>
                                <entry>chaîne</entry>
                                <entry>'1.1'</entry>
                            </row>

                            <row>
                                <entry>adapter</entry>
                                <entry>Classe adaptateur à utiliser (voyez <xref
                                linkend="zend.http.client.adapters" />)</entry>
                                <entry>mixed</entry>
                                <entry>'Zend_Http_Client_Adapter_Socket'</entry>
                            </row>

                            <row>
                                <entry>keepalive</entry>
                                <entry>Utilisation du pipelining <acronym>HTTP</acronym> (connexion ouverte après
                                déconnexion du client)</entry>
                                <entry>booléen</entry>
                                <entry><constant>FALSE</constant></entry>
                            </row>

                            <row>
                                <entry>storeresponse</entry>
                                <entry>Stockage ou non de la dernière réponse pour une récupération
                                ultérieure avec <methodname>getLastResponse()</methodname>. Si réglez à
                                <constant>FALSE</constant>, <methodname>getLastResponse()</methodname> retournera
                                <constant>NULL</constant>.</entry>
                                <entry>booléen</entry>
                                <entry><constant>TRUE</constant></entry>
                            </row>

                            <row>
                                <entry>encodecookies</entry>
                                <entry>Whether to pass the cookie value through urlencode/urldecode.
                                Enabling this breaks support with some web servers.
                                Disabling this limits the range of values the cookies can contain.</entry>
                                <entry>boolean</entry>
                                <entry><constant>TRUE</constant></entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
            </para>
    </sect2>

    <sect2 id="zend.http.client.basic-requests">
        <title>Utilisation basique</title>

        <para>
            Exécuter des requêtes HTTP basiques est très simple grâce à la méthode
            <methodname>request()</methodname>, et ceci nécessite rarement plus d'une ligne de code : <example
                    id="zend.http.client.basic-requests.example-1">
                    <title>Requête GET simple</title>

                    <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client('http://example.org');
$response = $client->request();
]]></programlisting>
                </example> La méthode <methodname>request()</methodname> accepte un paramètre optionnel
            définissant la méthode HTTP, - GET, POST, PUT, HEAD, DELETE, TRACE, OPTIONS ou CONNECT -
            comme définies dans la RFC 2616 concernant le protocole HTTP <footnote>
                <para>
                    Voyez la RFC 2616 - <ulink
                    url="http://www.w3.org/Protocols/rfc2616/rfc2616.html"></ulink>.
                </para>
            </footnote>. Ces méthodes HTTP sont aussi définies en tant que constantes de classe,
            Zend_Http_Request::GET, Zend_Http_Request::POST, etc...
        </para>

        <para>
            Si aucune méthode de requêtage HTTP n'est définie, alors la dernière utilisée via
            <methodname>setMethod()</methodname> sera utilisée. Si <methodname>setMethod()</methodname> n'a jamais été
            appelée, GET est alors utilisée par défaut. <example
                    id="zend.http.client.basic-requests.example-2">
                    <title>Requêtes d'autres types que GET</title>

                    <programlisting language="php"><![CDATA[
// requête POST
$response = $client->request('POST');

// autre manière de faire :
$client->setMethod(Zend_Http_Client::POST);
$response = $client->request();
]]></programlisting>
                </example>
            </para>
    </sect2>

    <sect2 id="zend.http.client.parameters">
        <title>Ajouts de paramètres GET et POST</title>

        <para>
            Ajouter des paramètres GET à la requête HTTP est très simple. Vous pouvez les
            ajouter en tant que partie de l'URL désirée, ou en utilisant la méthode
            <methodname>setParameterGet()</methodname>. Celle-ci prend en premier paramètre le nom du paramètre
            GET, et en second sa valeur. Un tableau associatif peut aussi être utilisé. <example
                    id="zend.http.client.parameters.example-1">
                    <title>Ajouts de paramètres GET</title>

                    <programlisting language="php"><![CDATA[
// Avec la méthode setParameterGet
$client->setParameterGet('knight', 'lancelot');

// Ce qui est équivalent à :
$client->setUri('http://example.com/index.php?knight=lancelot');

// Ajout de plusieurs paramètres en un appel
$client->setParameterGet(array(
    'first_name'  => 'Bender',
    'middle_name' => 'Bending'
    'made_in'     => 'Mexico',
));
]]></programlisting>
                </example>
            </para>

        <para>
            Coté POST, c'est très similaire à GET, sauf que les paramètres POST doivent faire
            partie du corps de la requête. Il n'est donc pas possible de les ajouter dans l'URL.
            Utilisez simplement <methodname>setParameterPost()</methodname> de la même manière que sa soeur
            <methodname>setParameterGet()</methodname>. <example id="zend.http.client.parameters.example-2">
                    <title>Ajout de paramètres POST</title>

                    <programlisting language="php"><![CDATA[
// passage de paramètre POST simple
$client->setParameterPost('language', 'fr');

// Plusieurs paramètres, dont un avec plusieurs valeurs
$client->setParameterPost(array(
    'language'  => 'es',
    'country'   => 'ar',
    'selection' => array(45, 32, 80)
));
]]></programlisting>
                </example> Notez qu'en plus de paramètres POST, vous pouvez ajouter des paramètres
            GET à une requête POST. Le contraire n'est pas possible, ainsi les paramètres POST
            ajoutés à une requête GET seront acceptés certes, mais ignorés.
        </para>
    </sect2>

    <sect2 id="zend.http.client.accessing_last">
        <title>Accéder à la dernière requête, ou réponse</title>

        <para>
            <classname>Zend_Http_Client</classname> fournit un moyen d'accéder à la dernière
            requête qu'il a effectuée, ainsi qu'à la dernière réponse qu'il a reçue.
            <classname>Zend_Http_Client-&gt;getLastRequest()</classname> ne prends pas de paramètres
            et retourne la dernière requête sous forme de chaîne de caractères.
            <classname>Zend_Http_Client-&gt;getLastResponse()</classname> retourne elle la dernière
            réponse, mais sous forme d'objet <link
            linkend="zend.http.response">Zend_Http_Response</link>.
        </para>
    </sect2>
</sect1>