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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- EN-Revision: 1.15 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->

<refentry xml:id="function.setcookie" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>setcookie</refname>
  <refpurpose>Envoie un cookie</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <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><initializer>0</initializer></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><initializer>false</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>false</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>setcookie</function> définit un cookie qui sera envoyé
   avec le reste des en-têtes. Comme pour les autres en-têtes, les cookies
   doivent être envoyés <emphasis>avant</emphasis> tout autre sortie
   (c'est une restriction du protocole HTTP, pas de PHP). Cela vous impose
   d'appeler cette fonction avant toute balise <literal>&lt;html&gt;</literal>
   ou <literal>&lt;head&gt;</literal>.
  </para>
  <para>
   Une fois que le cookie a été placé, il est accessible dans les variables globales
   <varname>$_COOKIE</varname> ou bien
   <varname>$HTTP_COOKIE_VARS</varname> arrays.  Notez que les
   <link linkend="language.variables.superglobals">superglobales</link>
   telles que <varname>$_COOKIE</varname> sont disponibles en PHP depuis
   la version 4.1.0.
   Les valeurs de cookies existent aussi dans la variable
   <varname>$_REQUEST</varname>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <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. Comme l'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 cela (<emphasis>0</emphasis>).
  </para>
  <para>
   Veuillez lire
   <link xlink:href="&spec.cookies;"><literal>"Netscape cookie specification"</literal></link>
   pour le fonctionnement de chaque paramètre de <function>setcookie</function>.
   <variablelist>
    <varlistentry>
     <term><parameter>name</parameter></term>
     <listitem>
      <para>
       Le nom du cookie.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <para>
        La valeur du cookie. Cette valeur est stocké sur l'ordinateur du client ;
        ne stocker pas d'informations importantes.
        Le paramètre <parameter>name</parameter> est le 'cookiename',
        cette valeur est retrouvé en utilisant <varname>$_COOKIE['cookiename']</varname>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expire</parameter></term>
     <listitem>
      <para>
       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>. <literal>time()+60*60*24*30</literal>
       fera expirer le cookie dans 30 jours. Si vous ne spécifiez pas ce
       paramètre ou s'il vaut 0, le cookie expirera à la fin de la session
       (lorsque le navigateur sera fermé).
      </para>
      <para>
       <note>
        <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>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <para>
       Le chemin sur le serveur sur lequel le cookie sera disponible.
       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.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>domain</parameter></term>
     <listitem>
      <para>
       Le domaine où le cookie est disponible. 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
       <link xlink:href="&spec.cookies;">spécifications</link> pour plus de
       détails.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>secure</parameter></term>
     <listitem>
      <para>
       Indique si le cookie doit uniquement être transmis à travers une
       connexion sécurisée HTTPS depuis le client. 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;. Côté serveur,
       c'est au développeur d'envoyer ce genre de cookie uniquement sur les
       connexions sécurisées (e.g. en utilisant la variable
       <varname>$_SERVER["HTTPS"]</varname>).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>httponly</parameter></term>
     <listitem>
      <para>
       Lorsque ce paramètre vaut &true;, le cookie ne sera accessible que par
       le protocole HTTP. Cela signifie que le cookie ne sera pas accessible
       via des langages de scripts, comme Javascript. Cette configuration
       permet de limiter les attaques via XSS (bien qu'elle ne soit pas
       supporté par tous les navigateurs). Ajouté en PHP 5.2.0.
       &true; ou &false;
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   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;. Cela n'indique pas si le client accepte
   ou pas le cookie.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   Quelques exemples d'envoi de cookies :
   <example>
    <title>Exemple d'envoi d'un avec <function>setcookie</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$value = 'Valeur de test';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);  /* expire dans 1 heure */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", ".example.com", 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 :
  </para>
  <para>
   <informalexample>
    <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>
   </informalexample>
  </para>
  <para>
   <example>
    <title>Exemple d'effacement d'un cookie avec <function>setcookie</function></title>
    <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>
    <programlisting role="php">
<![CDATA[
<?php
// Utilisation de la date courante, moins une heure
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".example.com", 1);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>setcookie</function> et les tableaux</title>
    <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 :
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Définit les cookies
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// Après le rechargemet de la page, nous les affichons
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>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>5.2.0</entry>
       <entry>
        Le paramètre <parameter>httponly</parameter> a été ajouté.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <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; ou dans votre fichier de configuration
    de votre serveur.
   </para>
  </note>
  <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
      que ls autres arguments sont exactement les mêmes que lors du
      positionnement du cookie, alors le cookie sera effacé du client.
      En interne, l'effacement est réalisé en positionnant la valeur à
      'deleted' et la date d'expiration à une année dans le passé.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Du fait que l'assignation d'une valeur valant &false; à un cookie
      tente de l'effacer, vous ne devriez pas utiliser de &boolean;.
      À 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> pour placer un cookie
      avec des noms et des valeurs multiples. Il n'est pas recommandé d'utiliser
      la fonction <function>serialize</function> pour réaliser ceci, car
      cela peut conduire à des problèmes de sécurité.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <simpara>
   Les appels multiples à la fonction <function>setcookie</function>
   seront effectués dans l'ordre.
  </simpara>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>header</function></member>
    <member><function>setrawcookie</function></member>
    <member>La <link linkend="features.cookies">section sur les cookies</link></member>
    <member><link xlink:href="&url.rfc;2109">RFC 2109</link></member>
    <member><link xlink:href="&url.rfc;2965">RFC 2965</link></member>
   </simplelist>
  </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
-->