doc-fr/reference/http/functions/setcookie.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.20 $ -->
<!-- EN-Revision: 1.33 Maintainer: yannick Status: ready -->
  <refentry id="function.setcookie">
   <refnamediv>
    <refname>setcookie</refname>
    <refpurpose>Envoie un cookie</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <methodsynopsis>
     <type>bool</type><methodname>setcookie</methodname>
     <methodparam><type>string</type><parameter>name</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>value</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>expire</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>domain</parameter></methodparam>
     <methodparam choice="opt"><type>bool</type><parameter>secure</parameter></methodparam>
    </methodsynopsis>
    <para>
     <function>setcookie</function> définit un cookie qui sera envoyé
     avec le reste des en-têtes. Les cookies doivent passer avant tout autre
     en-tête (c'est une restriction des cookies, pas de &php;). Cela vous impose
     d'appeler cette fonction avant toute balise <literal>&lt;html&gt;</literal>
     ou <literal>&lt;head&gt;</literal>. Si quelque chose a été envoyé avant l'appel
     à cette fonction, <function>setcookie</function> échouera et retournera &false;.
     Si <function>setcookie</function> réussi, elle retournera &true;.
     Celà n'indique pas si le client accepte ou pas le cookie.
    </para>
    <note>
     <para>
      Depuis &php; 4, vous pouvez utiliser la bufferisation de sortie pour pouvoir
      envoyer du contenu avant d'appeler cette fonction, avec la contrepartie
      que toute votre page sera envoyée en une fois. Vous pouvez faire cela
      en appelant <function>ob_start</function> et <function>ob_end_flush</function>
      dans votre script, ou en activant la directive <literal>output_buffering</literal>
      dans votre fichier de configuration &php.ini;.
     </para>
    </note>
    <para>
     Tous les arguments sauf <parameter>name</parameter> (nom) sont optionnels.
     Si seul le nom est présent, le cookie portant ce nom sera
     supprimé du navigateur de l'internaute. Vous pouvez aussi utiliser une
     chaîne vide comme valeur, pour ignorer un argument. Parceque 'argument
     <parameter>expire</parameter> est un entier,
     il ne peut pas être ignoré avec une chaîne vide, vous devez utiliser le zéro pour celà
     (<emphasis>0</emphasis>). Le tableau suivant explique chaque paramètre de la
     fonction <function>setcookie</function>. Veuillez lire
     <ulink url="&spec.cookies;">"Netscape cookie specification"</ulink> pour le fonctionnement
     de chaque paramètre de <function>setcookie</function> ainsi que la
     <ulink url="&url.rfc;2965">RFC 2965</ulink> pour des compléments d'informations sur
     les cookies HTTP.
    </para>
    <para>
     <table>
      <title>Description des paramètres de <function>setcookie</function></title>
      <tgroup cols="3">
       <thead>
        <row>
         <entry>Paramètre</entry>
         <entry>Description</entry>
         <entry>Exemples</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry><parameter>name</parameter></entry>
         <entry>
          Le nom du cookie.
         </entry>
         <entry>
          'cookiename' est appelé via <varname>$_COOKIE['cookiename']</varname>
         </entry>
        </row>
        <row>
         <entry><parameter>value</parameter></entry>
         <entry>
          La valeur du cookie. Cette valeur est stocké sur l'ordinateur du client ;
          ne stocker pas d'informations importantes.
         </entry>
         <entry>
          Le paramètre <parameter>name</parameter> est le 'cookiename',
          cette valeur est retrouvé en utilisant <varname>$_COOKIE['cookiename']</varname>
         </entry>
        </row>
        <row>
         <entry><parameter>expire</parameter></entry>
         <entry>
          Le temps après lequel le cookie expire. C'est un timestamp Unix, donc, ce sera un
          nombre de secondes depuis l'époque Unix (1 Janvier 1970). En d'autres mots, vous devriez
          fixer cette valeur à l'aide de la fonction <function>time</function> et en y ajoutant
          le nombre de secondes après lequel on veut que le cookie expire. Vous ouvez utiliser aussi
          <function>mktime</function>.
         </entry>
         <entry>
          <literal>time()+60*60*24*30</literal> fera expirer le cookie dans 30 jours. Si vous ne
          spécifiez pas ce paramètre, le cookie expirera à la fin de la session (lorsque le navigateur
          sera fermé).
         </entry>
        </row>
        <row>
         <entry><parameter>path</parameter></entry>
         <entry>
          Le chemin sur le serveur sur lequel le cookie sera disponible.
         </entry>
         <entry>
          Si la valeur est <literal>'/'</literal>, le cookie sera disponible sur l'ensemble du domaine
          <parameter>domain</parameter>. Si la valeur est <literal>'/foo/'</literal>,
          le cookie sera uniquement disponible dans le répertoire <literal>/foo/</literal> ainsi
          que tous ces sous-répertoires comme <literal>/foo/bar/</literal> du domaine
          <parameter>domain</parameter>. La valeur par défaut est le répertoire courant où
          le cookie a été défini.
         </entry>
        </row>
        <row>
         <entry><parameter>domain</parameter></entry>
         <entry>
          Le domaine où le cookie est disponible.
         </entry>
         <entry>
          Pour rendre le cookie disponible sur tous les sous-domaines de example.com,
          vous devez mettre la valeur <literal>'.example.com'</literal>.
          Le point (<literal>.</literal>) n'est pas requis mais est nécessaire pour la compatibilité
          avec encore plus de navigateurs. Positionnez le à <literal>www.example.com</literal>
          rendra le cookie disponible uniquement sur le sous-domaine <literal>www</literal>.
          Reportez-vous aux <ulink url="&spec.cookies;">spécifications</ulink> pour plus de détails.
         </entry>
        </row>
        <row>
         <entry><parameter>secure</parameter></entry>
         <entry>
          Indique si le cookie doit uniquement être transmis à travers une
          connexion sécurisée HTTPS. Lorsqu'il est positionné à &true;,
          le cookie ne sera positionné uniquement si la connexion sécurisée existe.
          La valeur par défaut est &false;.
         </entry>
         <entry>
          &zero; ou &one;
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     Une fois que le cookie a été placé, il est accessible dans les variables globales
     <link linkend="reserved.variables.cookies">$_COOKIE</link> ou bien
     <varname>$HTTP_COOKIE_VARS</varname> arrays.  Notez que les
     <link linkend="language.variables.superglobals">autoglobales</link>
     telles que <varname>$_COOKIE</varname> sont disponibles en &php; depuis
     la version <ulink url="&url.php.release4.1.0;">4.1.0</ulink>.
     <varname>$HTTP_COOKIE_VARS</varname> existe depuis &php; 3.
     Les valeurs de cookies existent aussi dans la variable
     <link linkend="reserved.variables.request">$_REQUEST</link>.
    </para>
    <note>
     <para>
      Si la directive &php; <link linkend="ini.register-globals">register_globals</link>
      est positionnée à <literal>on</literal>, la valeur du cookie est aussi disponible
      dans une variable. Dans l'exemple ci-dessous, <varname>$TestCookie</varname>
      existe. Il est vivement recommandé d'utiliser <varname>$_COOKIE</varname>.
     </para>
    </note>
    <para>
    Erreurs communes :
     <itemizedlist>
      <listitem>
       <simpara>
        Les cookies ne seront accessibles qu'au chargement de la prochaine page,
        ou au rechargement de la page courante. Pour tester si un cookie
        a été défini avec succès, vérifiez la présence du cookie au prochain chargement
        de la page avant que le cookie n'expire. Le délai d'expiration est défini
        en utilisant le paramètre <parameter>expire</parameter>.
        Une façon simple de vérifier
        le positionnement du cookie est d'utiliser <literal>print_r($_COOKIE);</literal>.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Les cookies doivent être effacés avec les mêmes paramètres
        que ceux utilisés lors de leur création.
        Si l'argument <parameter>value</parameter> est une chaîne vide ou vaut &false; et
        quelques autres arguments sont exactements les mêmes que lors du positionnement du cookie,
        alors le cookie sera effacé du client.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Du fait que l'assignation d'une valeur vallant &false; à un cookie tente de l'effacer,
        vous ne devriez pas utiliser de &boolean;. A la place, utilisez 
        <emphasis>0</emphasis> pour &false;
        et <emphasis>1</emphasis> pour &true;.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Les noms des cookies peuvent être des tableaux de noms et seront
        disponibles dans vos scripts &php; sous la forme de tableaux mais
        des cookies différents seront placés sur le client.
        Utilisez <function>explode</function> ou <function>serialize</function>
        pour placer un cookie avec des noms et des valeurs multiples.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <simpara>
     En &php; 3, les appels multiples à <function>setcookie</function> dans le
     même script seront effectués dans l'ordre inverse. Si vous essayez d'effacer
     un cookie avant d'insérer une nouvelle valeur, vous devez placer l'insertion
     avant l'effacement. Depuis &php; 4, les appels multiples à
     <function>setcookie</function> sont effectués dans un ordre naturel.
    </simpara>
    <para>
     Quelques exemples :
     <example>
      <title>Exemples avec <function>setcookie</function></title>
      <programlisting role="php">
<![CDATA[
<?php
$value = 'Valeur de test';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);  /* expire dans une heure */
setcookie("TestCookie", $value, time()+3600,"/~rasmus/",".utoronto.ca",1);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     Notez que la partie "valeur" du cookie sera automatiquement
     encodée URL lorsque vous envoyez le cookie et, lorsque
     vous le recevez, il sera automatiquement décodé,
     et affecté à la variable du même nom que
     le cookie. Si vous le voulez pas de ce comportement par défaut, vous
     pouvez utiliser la fonction <function>setrawcookie</function> si vous
     utilisez &php; 5. Pour voir le résultat, essayez les scripts suivants :
     <example>
      <title>Affectation des valeurs de cookie</title>
      <programlisting role="php">
<![CDATA[
<?php
// Afficher un cookie
echo $_COOKIE["TestCookie"];
echo $HTTP_COOKIE_VARS["TestCookie"];

// Une autre méthode pour afficher tous les cookies
print_r($_COOKIE);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     Lorsque vous effacez un cookie, vous devriez toujours vous assurer
     que sa date d'expiration est déjà passée, pour déclencher
     le mécanisme de votre navigateur. Voici comment procéder :
    </para>
    <para>
     <example>
      <title>Exemple d'effacement de cookies avec <function>setcookie</function></title>
      <programlisting role="php">
<![CDATA[
<?php
// utilisation de la date moins une heure
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".example.com", 1);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     Vous pouvez aussi utiliser les cookies avec des tableaux, en utilisant la
     notation des tableaux. Cela a pour effet de créer autant de
     cookies que votre tableau a d'éléments, mais lorsque
     les cookies seront reçus par votre script, les valeurs seront
     placées dans un tableau :
     <example>
      <title>Utilisation des tableaux avec <function>setcookie</function></title>
      <programlisting role="php">
<![CDATA[
<?php
setcookie("cookie[three]", "cookiethree" );
setcookie("cookie[two]", "cookietwo" );
setcookie("cookie[one]", "cookieone" );

// Après avoir rechargé la page :
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $name => $value) {
        echo "$name : $value <br />\n";
    }
}
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
three : cookiethree
two : cookietwo
one : cookieone
]]>
      </screen>
     </example>
    </para>
    <note>
     <para>
      Pour plus d'informations sur les cookies, voyez les spécifications
      de cookies de Netscape à <ulink url="&spec.cookies;">&spec.cookies;</ulink> et
      <ulink url="&url.rfc;2965">RFC 2965</ulink>.
     </para>
     <para>
      Vous pourrez noter que le paramètre <parameter>expire</parameter> prend un
      timestamp unique, et non pas la date au format <literal>Jour, JJ-Mois-AAAA
      HH:MM:SS GMT</literal>, car &php; fait la conversion en interne.
     </para>
     <para>
      Le paramètre <parameter>expire</parameter> est comparé avec le temps du client
      qui peut être différent de celui du serveur.
     </para>
    </note>
    <note>
     <simpara>
      Microsoft Internet Explorer 4 utilisé avec le Service Pack 1
      ne gère pas bien les cookies qui possèdent un
      paramètre <parameter>path</parameter>.
     </simpara>
     <simpara>
      Netscape Communicator 4.05 et Microsoft Internet Explorer 3.x
      semblent ne pas gérer correctement les cookies lorsque
      <parameter>path</parameter> et <parameter>expire</parameter> ne
      sont pas fournis.
     </simpara>
    </note>
    <para>
     Voir aussi
     <function>header</function>,
     <function>setrawcookie</function> ainsi que la
     <link linkend="features.cookies">section sur les cookies</link>.
    </para>
   </refsect1>
  </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->