setcookie
(PHP 4, PHP 5, PHP 7, PHP 8)
setcookie — Envoie un cookie
Description
Une fois que les cookies ont été placés, ils seront accessibles lors du prochain
chargement de page dans le tableau $_COOKIE.
Les valeurs des cookies
peuvent aussi exister dans la variable $_REQUEST.
Liste de paramètres
La » RFC 6265 est la référence pour
l'interprétation des paramètres passés à setcookie().
name
-
Le nom du cookie.
value
-
La valeur du cookie. Cette valeur est stockée sur l'ordinateur du client ;
ne stockez pas d'informations importantes.
Si le paramètre name
vaut 'cookiename'
,
cette valeur est récupéré avec $_COOKIE['cookiename'].
expires_or_options
-
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).
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 à time().
Par exemple time()+60*60*24*30
configurera le cookie pour
qu'il expire dans 30 jours. Une autre possibilité consiste à utiliser la
fonction mktime(). 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é).
Note:
Vous pourrez noter que le paramètre expires_or_options
prend un
horodatage unique, et non pas la date au format Jour, JJ-Mois-AAAA
HH:MM:SS GMT
, car PHP fait la conversion en interne.
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 ses
sous-répertoires comme /foo/bar/
dans le domaine
domain
. La valeur par défaut est le répertoire
courant où le cookie a été défini.
domain
-
Le (sous-)domaine pour lequel le cookie est disponible. Définir ceci à un
sous-domaine (tel que 'www.example.com'
) 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 ('example.com'
,
avec cet exemple).
Les anciens navigateurs continuant d'implémenter la
» RFC 2109 (obsolète)
peuvent nécessiter un .
pour rendre disponible
tous les sous-domaines.
secure
-
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 $_SERVER["HTTPS"]).
httponly
-
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
options
-
Un tableau associatif qui peut avoir comme clés
expires
, path
, domain
,
secure
, httponly
et samesite
.
Si une autre clé est présente une erreur de niveau
E_WARNING
est émise.
Les valeurs ont la même signification que celles décrits pour les paramètres
avec le même nom. La valeur de l'élément samesite
doit
être None
, Lax
ou Strict
.
Si une options autorisé n'est pas donnée alors sa valeur par défaut sera
identique à la valeur par défaut des paramètres explicite. Si l'élément
samesite
est omit, alors l'attribut SameSite du cookie
ne sera pas définie.
Note:
Pour définir un cookie qui inclut des attributs qui ne figurent pas parmi les clés répertoriées,
utilisez header().
Valeurs de retour
Si quelque chose a été envoyé sur la sortie standard 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.
Exemples
Les exemples suivants démontrent quelques façons d'envoyer des cookies.
Exemple #1 Exemple d'envoi d'un cookie avec setcookie()
<?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", true);
?>
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 ne souhaitez pas
ce comportement par défaut, vous pouvez utiliser la fonction
setrawcookie().
Pour voir le résultat, essayez les scripts suivants :
Exemple #2 Exemple d'effacement d'un cookie avec setcookie()
Pour effacer un cookie sur le client, vous devez toujours vous assurer
que sa date d'expiration est passée, pour déclencher
le mécanisme du navigateur client. Voici comment procéder :
<?php
// Définie la date d'expiration à une heure avant la date courante
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
Exemple #3 setcookie() et les tableaux
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 :
<?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) {
$name = htmlspecialchars($name);
$value = htmlspecialchars($value);
echo "$name : $value <br />\n";
}
}
?>
L'exemple ci-dessus va afficher :
three : cookiethree
two : cookietwo
one : cookieone
Note:
L'utilisation des caractères de séparation comme [
et
]
comme faisant partie du nom du cookie n'est pas
respectueux de la RFC 6265, section 4, mais est supposé être supporté
par les user agents, suivant la RFC 6265, section 5.
Notes
Note:
Vous pouvez utiliser un tampon 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 ou dans le fichier de configuration
de votre serveur.
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
expires_or_options
.
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 et que les autres
arguments sont exactement les mêmes que lors d'un appel setcookie() précédent,
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é.
-
Du fait que l'assignation d'une valeur valant
false
à un cookie
tente de l'effacer, vous ne devriez pas utiliser de booléen.
À 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é.
Les appels multiples à la fonction setcookie()
seront effectués dans l'ordre.