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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 6122a8317ca0068fc71f6a5167e0a2d99166ec7c Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<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><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>expires_or_options</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>path</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>domain</parameter><initializer>""</initializer></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>
  <simpara>Signature alternative disponible à partir de PHP 7.3.0 (pas supporté avec les paramètres nommés) :</simpara>
  <methodsynopsis>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
  <simpara>
   <function>setcookie</function> définit un cookie qui sera envoyé
   avec le reste des en-têtes HTTP. Comme pour les autres en-têtes, les cookies
   doivent être envoyés <emphasis>avant</emphasis> toute autre sortie du script
   (c'est une restriction du protocole HTTP, pas de PHP). Cela impose
   d'appeler cette fonction avant toute balise <literal>&lt;html&gt;</literal>
   ou <literal>&lt;head&gt;</literal> et aussi des caractères d'espacement blanc.
  </simpara>
  <simpara>
   Une fois que les cookies ont été placés, ils seront accessibles lors du prochain
   chargement de page dans le tableau <varname>$_COOKIE</varname>.
   Les valeurs des cookies
   peuvent aussi exister dans la variable <varname>$_REQUEST</varname>.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   La <link xlink:href="&url.rfc;6265">RFC 6265</link> est la référence pour
   l'interprétation des paramètres passés à <function>setcookie</function>.
   <variablelist>
    <varlistentry>
     <term><parameter>name</parameter></term>
     <listitem>
      <simpara>
       Le nom du cookie.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <simpara>
       La valeur du cookie. Cette valeur est stockée sur l'ordinateur du client ;
       ne stockez pas d'informations sensibles. Si le paramètre
       <parameter>name</parameter> vaut <literal>'cookiename'</literal>,
       cette valeur est récupérée avec <varname>$_COOKIE['cookiename']</varname>
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expires_or_options</parameter></term>
     <listitem>
      <simpara>
       Le temps après lequel le cookie expire. C'est un horodatage Unix, donc
       un nombre de secondes depuis l'époque Unix (1 janvier 1970).
       Une façon de définir cette valeur est d'ajouter le nombre de secondes avant
       que le cookie n'expire au résultat d'un appel à <function>time</function>.
       Par exemple <literal>time()+60*60*24*30</literal> configurera le cookie pour
       qu'il expire dans 30 jours. Une autre possibilité consiste à utiliser la
       fonction <function>mktime</function>. Si ce paramètre vaut <literal>0</literal>,
       ou s'il est omis, le cookie expirera à la fin de la session
       (lorsque le navigateur sera fermé).
      </simpara>
      <note>
       <simpara>
        Le paramètre <parameter>expires_or_options</parameter> prend un
        horodatage Unix, et non pas la date au format <literal>Jour, JJ-Mois-AAAA
        HH:MM:SS GMT</literal>, car PHP fait la conversion en interne.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <simpara>
       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 ses
       sous-répertoires comme <literal>/foo/bar/</literal> dans le domaine
       <parameter>domain</parameter>. La valeur par défaut est le répertoire
       courant où le cookie a été défini.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>domain</parameter></term>
     <listitem>
      <simpara>
       Le (sous-)domaine pour lequel le cookie est disponible. Définir ceci à un
       sous-domaine (tel que <literal>'www.example.com'</literal>) rendra le cookie
       disponible pour ce sous-domaine ainsi que tous ses sous-domaines
       (par exemple : w2.www.example.com). Pour rendre le cookie
       disponible sur tout le domaine (ainsi que tous ses sous-domaines), définissez
       simplement la valeur avec le nom de domaine (<literal>'example.com'</literal>,
       avec cet exemple).
      </simpara>
      <simpara>
       Les anciens navigateurs continuant d'implémenter la
       <link xlink:href="&url.rfc;2109">RFC 2109</link> (obsolète)
       peuvent nécessiter un <literal>.</literal> pour rendre disponible
       tous les sous-domaines.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>secure</parameter></term>
     <listitem>
      <simpara>
       Indique si le cookie doit uniquement être transmis à travers une
       connexion sécurisée HTTPS depuis le client. Lorsque ce paramètre
       vaut &true;, le cookie ne sera envoyé que si la connexion est sécurisée.
       Côté serveur, c'est au développeur d'envoyer ce genre de cookie
       uniquement sur les connexions sécurisées (par exemple, en utilisant
       la variable <varname>$_SERVER["HTTPS"]</varname>).
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>httponly</parameter></term>
     <listitem>
      <simpara>
       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. Il a été suggéré que cette
       configuration permet de limiter les attaques via XSS (bien qu'elle ne soit
       pas supportée par tous les navigateurs), néanmoins ce fait est souvent contesté.
       &true; ou &false;
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <simpara>
       Un &array; associatif qui peut avoir comme clés
       <literal>expires</literal>, <literal>path</literal>, <literal>domain</literal>,
       <literal>secure</literal>, <literal>httponly</literal> et <literal>samesite</literal>.
       Les valeurs ont la même signification que celles décrites pour les paramètres
       avec le même nom. La valeur de l'élément <literal>samesite</literal> doit
       être <literal>None</literal>, <literal>Lax</literal> ou <literal>Strict</literal>.
       Si une option autorisée n'est pas donnée, alors sa valeur par défaut sera
       identique à la valeur par défaut des paramètres explicites. Si l'élément
       <literal>samesite</literal> est omis, alors l'attribut SameSite du cookie
       ne sera pas défini.
      </simpara>
      <note>
       <simpara>
        Pour définir un cookie qui inclut des attributs qui ne figurent pas parmi les clés répertoriées,
        utiliser <function>header</function>.
       </simpara>
      </note>
      <note>
       <simpara>
        Si <literal>samesite</literal> vaut <literal>"None"</literal>, alors
        <literal>secure</literal> doit également être activé, sinon le cookie sera
        bloqué par le client.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   Si quelque chose a été envoyé sur la sortie standard avant l'appel
   à cette fonction, <function>setcookie</function> échouera et
   retournera &false;. Si <function>setcookie</function> réussit,
   elle retournera &true;.
   Cela n'indique pas si le client accepte ou non le cookie.
  </simpara>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Si le tableau <parameter>options</parameter> contient une clé non supportée,
   une <exceptionname>ValueError</exceptionname> est lancée.
  </para>
  <para>
   Antérieur à PHP 8.0.0, si le tableau <parameter>options</parameter> contenait
   une clé non supportée, une erreur de niveau <constant>E_WARNING</constant>
   était émise.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.2.0</entry>
      <entry>
       La date du cookie est au format <literal>'D, d M Y H:i:s \G\M\T'</literal> ;
       précédemment c'était <literal>'D, d-M-Y H:i:s T'</literal>.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Si le tableau <parameter>options</parameter> contient une clé non supportée,
       une <exceptionname>ValueError</exceptionname> est désormais lancée ;
       précédemment, ces clés étaient ignorées avec une erreur
       de niveau <constant>E_WARNING</constant>.
      </entry>
     </row>
     <row>
      <entry>7.3.0</entry>
      <entry>
       Une signature alternative supportant un tableau
       d'<parameter>options</parameter> a été ajoutée. Cette signature supporte
       également la définition de l'attribut SameSite du cookie.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <simpara>
   Les effets des exemples suivants peuvent être observés en utilisant la liste
   des cookies des outils de développement du navigateur (généralement dans
   l'onglet Stockage ou Application).
  </simpara>
  <example>
   <title>Exemple d'envoi d'un cookie avec <function>setcookie</function></title>
   <programlisting role="php">
<![CDATA[
<?php

$value = 'something from somewhere';

// Définit un "cookie de session" qui expire lorsque le navigateur est fermé
setcookie("TestCookie", $value);
// Définit un cookie qui expire dans 1 heure
setcookie("TestCookie", $value, time()+3600);
// Définit un cookie qui s'applique uniquement à un chemin spécifique sur un domaine spécifique
// Notez que le domaine utilisé devrait correspondre au domaine du site
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);

?>
]]>
   </programlisting>
  </example>
  <simpara>
   À noter que la partie "valeur" du cookie sera automatiquement
   encodée URL par PHP. Cela peut être évité en utilisant la fonction
   <function>setrawcookie</function> à la place.
  </simpara>
  <simpara>
   Pour voir le contenu des cookies définis dans l'exemple ci-dessus lors d'une
   requête ultérieure :
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
// Afficher un cookie
echo $_COOKIE["TestCookie"];

// Une autre façon de déboguer/tester est d'afficher tous les cookies
print_r($_COOKIE);
?>
]]>
   </programlisting>
  </informalexample>
  <example>
   <title>Exemple d'effacement d'un cookie avec <function>setcookie</function></title>
   <simpara>
    Pour supprimer un cookie, définissez sa date d'expiration à une valeur
    dans le passé (mais pas zéro, qui est réservé aux cookies de session).
   </simpara>
   <simpara>
    Pour supprimer les cookies définis dans l'exemple précédent :
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
// Définit la date d'expiration à une heure dans le passé
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><function>setcookie</function> et les tableaux</title>
   <simpara>
    Un "tableau de cookies" peut être défini en utilisant la notation tableau
    dans le nom du cookie. Cela a pour effet de créer autant de cookies qu'il
    y a d'éléments dans le tableau, mais lorsque le cookie est reçu par le
    script, les valeurs sont toutes placées dans un tableau avec le nom du
    cookie :
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
// Définit les cookies
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// Après le rechargement de la page, nous les affichons
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $name => $value) {
        $name = htmlspecialchars($name);
        $value = htmlspecialchars($value);
        echo "$name : $value <br />\n";
    }
}
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
three : cookiethree
two : cookietwo
one : cookieone
]]>
   </screen>
  </example>
  <note>
   <simpara>
    L'utilisation des caractères de séparation comme <literal>[</literal> et
    <literal>]</literal> comme faisant partie du nom du cookie n'est pas
    conforme à la RFC 6265, section 4, mais est supposée être supportée
    par les user agents, suivant la RFC 6265, section 5.
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    La mise en tampon de sortie peut être utilisée pour permettre la sortie du
    script avant l'appel à cette fonction. Toute sortie sera mise en tampon
    jusqu'à ce qu'elle soit vidée (soit explicitement, soit à la fin de
    l'exécution du script). Cela se fait en appelant <function>ob_start</function>
    et <function>ob_end_flush</function> dans le script, ou en activant la
    directive de configuration <literal>output_buffering</literal> dans le
    fichier &php.ini; ou dans les fichiers de configuration du serveur.
   </simpara>
  </note>
  <para>
   Erreurs courantes :
   <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>expires_or_options</parameter>.
      Une façon simple de vérifier l'existence 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 et que les autres
      arguments correspondent exactement à un appel <function>setcookie</function> précédent,
      alors le cookie avec le nom spécifié sera supprimé du client distant.
      En interne, cela est réalisé en positionnant la valeur à
      <literal>'deleted'</literal> et la date d'expiration dans le passé.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Du fait que l'assignation d'une valeur valant &false; à un cookie
      tente de l'effacer, les valeurs booléennes ne devraient pas être utilisées.
      À la place, utiliser <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 les scripts PHP sous la forme de tableaux, mais
      des cookies différents seront placés sur le navigateur.
      Utiliser <function>json_encode</function> pour définir un cookie
      avec des noms et des valeurs multiples. Il n'est pas recommandé d'utiliser
      la fonction <function>serialize</function> pour cela, 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;
  <simplelist>
   <member><function>header</function></member>
   <member><function>setrawcookie</function></member>
   <member><link linkend="features.cookies">Section sur les cookies</link></member>
   <member><link xlink:href="&url.rfc;6265">RFC 6265</link></member>
   <member><link xlink:href="&url.rfc;2109">RFC 2109</link></member>
  </simplelist>
 </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:"~/.phpdoc/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
-->