setcookie

(PHP 4, PHP 5, PHP 7, PHP 8)

setcookieEnvoie un cookie

Description

setcookie(
    string $name,
    string $value = "",
    int $expires_or_options = 0,
    string $path = "",
    string $domain = "",
    bool $secure = false,
    bool $httponly = false
): bool

Signature alternative disponible à partir de PHP 7.3.0 (pas supporté avec les paramètres nommés) :

setcookie(string $name, string $value = "", array $options = []): bool

setcookie() 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 du script (c'est une restriction du protocole HTTP, pas de PHP). Cela impose d'appeler cette fonction avant toute balise <html> ou <head> et aussi des caractères d'espacement blanc.

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 sensibles. Si le paramètre name vaut 'cookiename', cette valeur est récupérée avec $_COOKIE['cookiename']
expires_or_options
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 à 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 ce paramètre vaut 0, ou s'il est omis, le cookie expirera à la fin de la session (lorsque le navigateur sera fermé).

Note: Le paramètre expires_or_options prend un horodatage Unix, 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écrites pour les paramètres avec le même nom. La valeur de l'élément samesite doit être None, Lax ou Strict. 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 samesite est omis, alors l'attribut SameSite du cookie ne sera pas défini.

Note: Pour définir un cookie qui inclut des attributs qui ne figurent pas parmi les clés répertoriées, utilisez header().

Note: Si samesite vaut "None", alors secure doit également être activé, sinon le cookie sera bloqué par le client.

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éussit, elle retournera true. Cela n'indique pas si le client accepte ou non le cookie.

Historique

Version Description
8.2.0 La date du cookie est au format 'D, d M Y H:i:s \G\M\T' ; précédemment c'était 'D, d-M-Y H:i:s T'.
7.3.0 Une signature alternative supportant un tableau d'options a été ajoutée. Cette signature supporte également la définition de l'attribut SameSite du cookie.

Exemples

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).

Exemple #1 Exemple d'envoi d'un cookie avec setcookie()

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

?>

Notez que la partie "valeur" du cookie sera automatiquement encodée URL par PHP. Cela peut être évité en utilisant la fonction setrawcookie() à la place.

Pour voir le contenu des cookies définis dans l'exemple ci-dessus lors d'une requête ultérieure :

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

// Une autre façon de déboguer/tester est d'afficher tous les cookies
print_r($_COOKIE);
?>

Exemple #2 Exemple d'effacement d'un cookie avec setcookie()

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).

Pour supprimer les cookies définis dans l'exemple précédent :

<?php
// Définit la date d'expiration à une heure dans le passé
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>

Exemple #3 setcookie() et les tableaux

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 :

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

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 conforme à la RFC 6265, section 4, mais est supposé être supporté par les user agents, suivant la RFC 6265, section 5.

Notes

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

Erreurs courantes :

  • 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 l'existence 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 correspondent exactement à un appel setcookie() 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 à 'deleted' et la date d'expiration dans le passé.
  • 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, 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 navigateur. Utilisez json_encode() pour définir un cookie avec des noms et des valeurs multiples. Il n'est pas recommandé d'utiliser la fonction serialize() pour cela, car cela peut conduire à des problèmes de sécurité.

Les appels multiples à la fonction setcookie() seront effectués dans l'ordre.

Voir aussi

add a note

User Contributed Notes 14 notes

up
397
walterquez
13 years ago
Instead of this:
<?php setcookie( "TestCookie", $value, time()+(60*60*24*30) ); ?>

You can this:
<?php setcookie( "TestCookie", $value, strtotime( '+30 days' ) ); ?>
up
277
Bachsau
13 years ago
Want to remove a cookie?

Many people do it the complicated way:
setcookie('name', 'content', time()-3600);

But why do you make it so complicated and risk it not working, when the client's time is wrong? Why fiddle around with time();

Here's the easiest way to unset a cookie:
setcookie('name', 'content', 1);

Thats it.
up
95
Anonymous
5 years ago
Just an example to clarify the use of the array options, especially since Mozilla is going to deprecate / penalise the use of SameSite = none,  which is used by default if not using array options. 

<?php
$arr_cookie_options = array (
                'expires' => time() + 60*60*24*30, 
                'path' => '/', 
                'domain' => '.example.com', // leading dot for compatibility or use subdomain
                'secure' => true,     // or false
                'httponly' => true,    // or false
                'samesite' => 'None' // None || Lax  || Strict
                );
setcookie('TestCookie', 'The Cookie Value', $arr_cookie_options);    
?>
up
24
nacho at casinelli dot com
8 years ago
It's worth a mention: you should avoid dots on cookie names.

<?php
// this will actually set 'ace_fontSize' name:
setcookie( 'ace.fontSize', 18 );
?>
up
36
paul nospam AT nospam sitepoint dot com
19 years ago
Note when setting "array cookies" that a separate cookie is set for each element of the array.

On high traffic sites, this can substantially increase the size of subsequent HTTP requests from clients (including requests for static content on the same domain).

More importantly though, the cookie specification says that browsers need only accept 20 cookies per domain.  This limit is increased to 50 by Firefox, and to 30 by Opera, but IE6 and IE7 enforce the limit of 20 cookie per domain.  Any cookies beyond this limit will either knock out an older cookie or be ignored/rejected by the browser.
up
43
Anonymous
18 years ago
something that wasn't made clear to me here and totally confused me for a while was that domain names must contain at least two dots (.), hence 'localhost' is invalid and the browser will refuse to set the cookie! instead for localhost you should use false.

to make your code work on both localhost and a proper domain, you can do this:

<?php

$domain = ($_SERVER['HTTP_HOST'] != 'localhost') ? $_SERVER['HTTP_HOST'] : false;
setcookie('cookiename', 'data', time()+60*60*24*365, '/', $domain, false);

?>
up
2
ilya at ilya dot top
1 year ago
In any web browser there is a very commonly used option "Open previous windows and tabs" which is disabled by default, but many people enable it.
When this option is active, the web browser, when closing and reopening, instead of executing the termination and starting a new session, saves and restores the current session along with session cookies and sessionStorage.
Both session cookies and sessionStorage, contrary to expectations, can live for a very long time until the user closes the tab before closing the web browser.
If you want a cookie, for example with a time offset, to be guaranteed to have a short lifetime, you should explicitly specify this short lifetime, rather than relying on self-deletion on the session cookie.
up
16
gabe at fijiwebdesign dot com
18 years ago
If you want to delete all cookies on your domain, you may want to use the value of:

<?php $_SERVER['HTTP_COOKIE'] ?>

rather than:

<?php $_COOKIE ?>

to dertermine the cookie names. 
If cookie names are in Array notation, eg: user[username] 
Then PHP will automatically create a corresponding array in $_COOKIE. Instead use $_SERVER['HTTP_COOKIE'] as it mirrors the actual HTTP Request header. 

<?php

// unset cookies
if (isset($_SERVER['HTTP_COOKIE'])) {
    $cookies = explode(';', $_SERVER['HTTP_COOKIE']);
    foreach($cookies as $cookie) {
        $parts = explode('=', $cookie);
        $name = trim($parts[0]);
        setcookie($name, '', time()-1000);
        setcookie($name, '', time()-1000, '/');
    }
}

?>
up
7
synnus at gmail dot com
5 years ago
The " PHPSESSID " cookie will soon be rejected because its " sameSite " attribute is set to " none " or an invalid value, and without " secure " attribute. To learn more about the "sameSite" attribute, visit https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie/SameSite.

<?php
 ini_set("session.cookie_secure", 1);
 session_start();

my PHP code .... 

?>
up
6
ellert at vankoperen dot nl
11 years ago
Caveat: if you use URL RewriteRules to get stuff like this: domain.com/bla/stuf/etc into parameters, you might run into a hickup when setting cookies.
At least in my setup a change in one of the parameters resulted in the cookie not being 'there' anymore.
The fix is simple: specify the domain. '/' will usualy do fine.
up
3
Anonymous
15 years ago
A period in a cookie name (like user.name) seems to show up in the $_COOKIE array as an underscore (so user_name). This means that for example $_COOKIE["user_name"] must be used to read a cookie that has been set with setcookie("user.name" ...), which is already rather confusing. 

Furthermore the variable $_COOKIE["user_name"] will retain the value set by setcookie("user.name" ...) and no amount of calling setcookie("user_name" ...) will alter this value. This is rather trivially fixed by clearing the "user.name" cookie, but it can take a while to realize this since there's only "user_name" in $_COOKIE.

Hope this saves someone some time.
up
3
laffen
16 years ago
Note that the $_COOKIE variable not will hold multiple cookies with the same name. It is legitimate to set two cookies with the same name to the same host where the sub domain is different. 
<?php
setcookie("testcookie", "value1hostonly", time(), "/", ".example.com", 0, true);
setcookie("testcookie", "value2subdom", time(), "/", "subdom.example.com", 0, true);
?>
The next request from the browser will have both cookies in the $_SERVER['HTTP_COOKIE'] variable, but only one of them will be found in the $_COOKIE variable. Requests to subdom.example.com will have both cookies, while browser request to example.com or www.example.com only sends the cookie with the "value1hostonly" value.

<?php
$kaker = explode(";", $_SERVER['HTTP_COOKIE']);
foreach($kaker as $val){
    $k = explode("=", $val);
    echo trim($k[0]) . " => " . $k[1];
}

// output
testcookie => value1hostonly
testcookie => value2subdom

?>
up
0
alexsvetalena at mail dot ru
6 months ago
Please keep in mind that if you call setcookie() several times during the script execution (even for the same name, domain and path), then Set-Cookie header will be sent several times, and only after receiving all of them, client browser will "merge" them, replacing first value for the cookie with the next etc.

This may cause very large headers length sometimes, so you'll have to either increase buffers for your web server; change your code logic to determine all possibly-changing parameters values right from the start; implement some sort of global Response object keeping all the data, including cookies as well, till the end of processing (sort of optimized output beffering); or just avoid storing any large data in cookies.
up
-2
steven at sovstack dot com
1 year ago
As of PHP 7.3, you can use this syntax:

setcookie( $name,  $value,  $options)

Be aware that the array in $options is not fully compatible with array key names. In other words, the order of your array values matters regardless of the array key names.

<?PHP

// Correct (with key names):
setcookie(
    'my_cookie',
    'my_value',
    [
        'expires' => time() + 3600,
        'path' => '/',
    ]
);

// Correct (without key names):
setcookie(
    'my_cookie',
    'my_value',
    [
        time() + 3600, // expires
        '/' // path
    ]
);

// Incorrect Usage (wrong order as key names are ignored):
setcookie(
    'my_cookie',
    'my_value',
    [
        'path' => '/', // WRONG: should be 2nd
        'expires' => time() + 3600, // WRONG: should be 1st
    ]
);

// Here's the correct order of the $options array with default values:
$options = [
    'expires' => 0,
    'path' => "",
    'domain' => "",
    'secure' => false,
    'httponly' => false
];

setcookie(
    'my_cookie',
    'my_value',
    $options 
);

?>

If you do not provide options, the default values will be used.
To Top