Manuel PHP
PrécédentSuivant

setcookie

(PHP 3, PHP 4 , PHP 5)

setcookie -- Envoie un cookie

Description

bool setcookie ( string name [, string value [, int expire [, string path [, string domain [, bool secure]]]]] )

setcookie() 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 <html> ou <head>. Si quelque chose a été envoyé avant l'appel à cette fonction, setcookie() échouera et retournera FALSE. Si setcookie() réussi, elle retournera TRUE. Cela n'indique pas si le client accepte ou pas le cookie.

Note : 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 ob_start() et ob_end_flush() dans votre script, ou en activant la directive output_buffering dans votre fichier de configuration php.ini.

Tous les arguments sauf name (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 expire est un entier, il ne peut pas être ignoré avec une chaîne vide, vous devez utiliser le zéro pour cela (0). Le tableau suivant explique chaque paramètre de la fonction setcookie(). Veuillez lire "Netscape cookie specification" pour le fonctionnement de chaque paramètre de setcookie() ainsi que la RFC 2965 pour des compléments d'informations sur les cookies HTTP.

Tableau 1. Description des paramètres de setcookie()

ParamètreDescriptionExemples
name Le nom du cookie. 'cookiename' est appelé via $_COOKIE['cookiename']
value La valeur du cookie. Cette valeur est stocké sur l'ordinateur du client ; ne stocker pas d'informations importantes. Le paramètre name est le 'cookiename', cette valeur est retrouvé en utilisant $_COOKIE['cookiename']
expire 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 time() et en y ajoutant le nombre de secondes après lequel on veut que le cookie expire. Vous ouvez utiliser aussi mktime(). time()+60*60*24*30 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é).
path Le chemin sur le serveur sur lequel le cookie sera disponible. Si la valeur est '/', le cookie sera disponible sur l'ensemble du domaine domain. Si la valeur est '/foo/', le cookie sera uniquement disponible dans le répertoire /foo/ ainsi que tous ces sous-répertoires comme /foo/bar/ du domaine domain. La valeur par défaut est le répertoire courant où le cookie a été défini.
domain 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 '.example.com'. Le point (.) n'est pas requis mais est nécessaire pour la compatibilité avec encore plus de navigateurs. Positionnez le à www.example.com rendra le cookie disponible uniquement sur le sous-domaine www. Reportez-vous aux spécifications pour plus de détails.
secure 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. 0 ou 1

Une fois que le cookie a été placé, il est accessible dans les variables globales $_COOKIE ou bien $HTTP_COOKIE_VARS arrays. Notez que les autoglobales telles que $_COOKIE sont disponibles en PHP depuis la version 4.1.0. $HTTP_COOKIE_VARS existe depuis PHP 3. Les valeurs de cookies existent aussi dans la variable $_REQUEST.

Note : Si la directive PHP register_globals est positionnée à on, la valeur du cookie est aussi disponible dans une variable. Dans l'exemple ci-dessous, $TestCookie existe. Il est vivement recommandé d'utiliser $_COOKIE.

Erreurs communes :

En PHP 3, les appels multiples à setcookie() 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 à setcookie() sont effectués dans un ordre naturel.

Quelques exemples :

Exemple 1. Exemples avec setcookie()

<?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);
?>

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 setrawcookie() si vous utilisez PHP 5. Pour voir le résultat, essayez les scripts suivants :

Exemple 2. Affectation des valeurs de cookie

<?php
// Afficher un cookie
echo $_COOKIE["TestCookie"];
echo $HTTP_COOKIE_VARS["TestCookie"];

// Une autre méthode pour afficher tous les cookies
print_r($_COOKIE);
?>

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 :

Exemple 3. Exemple d'effacement de cookies avec setcookie()

<?php
// utilisation de la date moins une heure
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".example.com", 1);
?>

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 :

Exemple 4. Utilisation des tableaux avec setcookie()

<?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";
    }
}
?>

L'exemple ci-dessus va afficher :

three : cookiethree
two : cookietwo
one : cookieone

Note : Les RFCs suivantes peuvent être utiles : RFC 2109 et RFC 2695.

Vous pourrez noter que le paramètre expire prend un timestamp unique, et non pas la date au format Jour, JJ-Mois-AAAA HH:MM:SS GMT, car PHP fait la conversion en interne.

Le paramètre expire est comparé avec le temps du client qui peut être différent de celui du serveur.

Note : Microsoft Internet Explorer 4 utilisé avec le Service Pack 1 ne gère pas bien les cookies qui possèdent un paramètre path.

Netscape Communicator 4.05 et Microsoft Internet Explorer 3.x semblent ne pas gérer correctement les cookies lorsque path et expire ne sont pas fournis.

Voir aussi header(), setrawcookie() ainsi que la section sur les cookies.

PrécédentSommaireSuivant
headers_sentNiveau supérieursetrawcookie