(PHP 4, PHP 5, PHP 7)
setcookie — Envoie un cookie
$name
[, string $value = ""
[, int $expires = 0
[, string $path = ""
[, string $domain = ""
[, bool $secure = FALSE
[, bool $httponly = FALSE
]]]]]] ) : bool$name
[, string $value = ""
[, array $options = []
]] ) : boolsetcookie() 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 avant toute autre sortie (c'est une restriction du protocole HTTP, pas de PHP). Cela vous impose d'appeler cette fonction avant toute balise <html> ou <head> et aussi des charactères d'espacement blanc.
Une fois que les cookies ont été placés, ils seront accessible lors du prochain chargement de page dans le tableau $_COOKIE. Les valeurs des cookies peuvent aussi exister dans la variable $_REQUEST.
La » RFC 6265 est la référence pour l'interprétation des paramètres passés à setcookie().
nameLe 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'].
expiresLe 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 termes, vous devriez fixer cette valeur à l'aide de la fonction time() en y ajoutant le nombre de secondes après lequel on veut que le cookie expire. Vous pouvez utiliser aussi mktime(). time()+60*60*24*30 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é).
Note:
Vous pourrez noter que le paramètre
expiresprend 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.
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.
domainLe (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é.
Ajouté en PHP 5.2.0.
TRUE ou FALSE
optionsUn tableau associatif qui peut avoir comme clés expires, path, domain, secure, httponly et samesite. 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 soit être Lax soit 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.
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.
Quelques exemples d'envoi de 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", 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 ne souhaitez pas ce comportement par défaut, vous pouvez utiliser la fonction setrawcookie(). Pour voir le résultat, essayez les scripts suivants :
<?php
// Afficher un cookie
echo $_COOKIE["TestCookie"];
// Une autre méthode pour afficher tous les cookies
print_r($_COOKIE);
?>
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
| Version | Description |
|---|---|
| 7.3.0 |
Une signature alternative supportant un tableau
d'options a été ajouté. Cette signature supporte
la définition de l'attribut SameSite du cookie.
|
| 5.5.0 | Un attribut Max-Age est maintenant inclus dans l'en-tête Set-Cookie envoyé au client. |
| 5.2.0 |
Le paramètre httponly a été ajouté.
|
Note:
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 ou dans le fichier de configuration de votre serveur.
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 :
expires.
Une façon simple de vérifier le positionnement du cookie est d'utiliser
print_r($_COOKIE);.
value est une chaîne vide ou vaut FALSE et
que les 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é.
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 appels multiples à la fonction setcookie() seront effectués dans l'ordre.