6.13 HTTP
6 Référence des fonctions
Manuel PHP
. Introduction
. Pré-requis
. Installation
. Configuration à l'exécution
. Types de ressources
. Constantes pré-définies
. header
. headers_list
. headers_sent
->setcookie
. setrawcookie
|
6.13.10 setcookie()Envoie un cookie[ Exemples avec setcookie ] PHP 3, PHP 4, PHP 5
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.
| Paramètre |
Description |
Exemples |
|
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 :
-
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
expire
.
Une façon simple de vérifier
le positionnement du cookie est d'utiliser
print_r($_COOKIE);
.
-
Les cookies doivent être effacés avec les mêmes paramètres
que ceux utilisés lors de leur création.
Si l'argument
value
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.
-
Du fait que l'assignation d'une valeur vallant
FALSE
à un cookie tente de l'effacer,
vous ne devriez pas utiliser de booléen . A la place, utilisez
0
pour
FALSE
et
1
pour
TRUE
.
-
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
explode
pour placer un cookie
avec des noms et des valeurs multiples. Il n'est pas recommandé d'utiliser
la fonction
serialize
pour réaliser ceci, car
cela peut conduire à des problèmes de sécurité.
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 :
| 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 :
| 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 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 :
| 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";
}
}
?>
|
| 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 .
|