PHP 8.5.0 Alpha 1 available for testing

setcookie

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

setcookieEnvía una cookie

Descripción

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

Firma alternativa disponible a partir de PHP 7.3.0 (no soportado con parámetros nombrados):

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

setcookie() define una cookie que será enviada junto con el resto de los encabezados HTTP. Al igual que con otros encabezados, las cookies deben ser enviadas antes de cualquier otra salida (esto es una restricción del protocolo HTTP, no de PHP). Esto impone la necesidad de llamar a esta función antes de cualquier etiqueta <html> o <head> y también de caracteres de espacio en blanco.

Una vez que las cookies han sido establecidas, estarán disponibles durante el próximo cargado de página en el array $_COOKIE. Los valores de las cookies también pueden existir en la variable $_REQUEST.

Parámetros

La » RFC 6265 es la referencia para la interpretación de los argumentos pasados a setcookie().

name

El nombre de la cookie.

value

El valor de la cookie. Este valor se almacena en el ordenador del cliente; no se deben almacenar información importante. Si el argumento name vale 'cookiename', este valor es recuperado con $_COOKIE['cookiename'].

expires_or_options

El tiempo después del cual la cookie expira. Esto es un timestamp Unix, por lo tanto, será un número de segundos desde la época Unix (1 de enero de 1970). Una forma de definir este valor es añadiendo el número de segundos antes de que la cookie expire al resultado de una llamada a time(). Por ejemplo time()+60*60*24*30 configurará la cookie para que expire en 30 días. Otra posibilidad es utilizar la función mktime(). Si no se especifica este argumento o si vale 0, la cookie expirará al final de la sesión (cuando el navegador se cierre).

Nota:

Se notará que el argumento expires_or_options toma un timestamp único, y no la fecha en formato Día, DD-Mes-AAAA HH:MM:SS GMT, ya que PHP realiza la conversión internamente.

path

La ruta en el servidor donde la cookie estará disponible. Si el valor es '/', la cookie estará disponible en todo el dominio domain. Si el valor es '/foo/', la cookie estará únicamente disponible en el directorio /foo/ así como todos sus subdirectorios como /foo/bar/ en el dominio domain. El valor por omisión es el directorio actual donde la cookie fue definida.

domain

El (sub-)dominio para el cual la cookie está disponible. Definir esto a un subdominio (tal como 'www.example.com') hará que la cookie esté disponible para este subdominio así como todos sus subdominios (por ejemplo: w2.www.example.com). Para hacer que la cookie esté disponible en todo el dominio (así como todos sus subdominios), simplemente defina el valor con el nombre de dominio ('example.com', en este ejemplo).

Los navegadores antiguos que continúan implementando la » RFC 2109 (obsoleta) pueden requerir un . para hacer disponible todos los subdominios.

secure

Indica si la cookie debe ser transmitida únicamente a través de una conexión segura HTTPS desde el cliente. Cuando este argumento vale true, la cookie solo será enviada si la conexión es segura. Del lado del servidor, es responsabilidad del desarrollador enviar este tipo de cookie únicamente en conexiones seguras (por ejemplo, utilizando la variable $_SERVER["HTTPS"]).

httponly

Cuando este argumento vale true, la cookie solo será accesible por el protocolo HTTP. Esto significa que la cookie no será accesible vía lenguajes de script, como Javascript. Se ha sugerido que esta configuración permite limitar ataques XSS (aunque no es soportada por todos los navegadores), sin embargo este hecho es frecuentemente cuestionado. true o false

options

Un tableau asociativo que puede tener como claves expires, path, domain, secure, httponly y samesite. Si otra clave está presente, se emite un error de nivel E_WARNING. Los valores tienen el mismo significado que los descritos para los argumentos con el mismo nombre. El valor del elemento samesite debe ser None, Lax o Strict. Si una opción autorizada no es dada, entonces su valor por omisión será idéntico al valor por omisión de los argumentos explícitos. Si el elemento samesite es omitido, entonces el atributo SameSite de la cookie no será definido.

Nota:

Para definir una cookie que incluye atributos que no figuran entre las claves listadas, utilice header().

Valores devueltos

Si algo fue enviado a la salida estándar antes de la llamada a esta función, setcookie() fallará y retornará false. Si setcookie() tiene éxito, retornará true. Esto no indica si el cliente acepta o no la cookie.

Historial de cambios

Versión Descripción
8.2.0 La fecha de la cookie está en formato 'D, d M Y H:i:s \G\M\T'; previamente era 'D, d-M-Y H:i:s T'.
7.3.0 Se añadió una firma alternativa que soporta un array de options. Esta firma soporta la definición del atributo SameSite de la cookie.

Ejemplos

Los siguientes ejemplos demuestran algunas formas de enviar cookies.

Ejemplo #1 Ejemplo de envío de una cookie con setcookie()

<?php

$value
= 'Valor de prueba';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600); /* expira en 1 hora */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);
?>

Tenga en cuenta que la parte "valor" de la cookie será automáticamente codificada URL al enviar la cookie y, al recibirla, será automáticamente decodificada y asignada a la variable con el mismo nombre que la cookie. Si no desea este comportamiento por omisión, puede utilizar la función setrawcookie(). Para ver el resultado, pruebe los siguientes scripts:

<?php
// Mostrar una cookie
echo $_COOKIE["TestCookie"];

// Otro método para mostrar todas las cookies
print_r($_COOKIE);
?>

Ejemplo #2 Ejemplo de borrado de una cookie con setcookie()

Para borrar una cookie en el cliente, siempre debe asegurarse de que su fecha de expiración haya pasado, para activar el mecanismo del navegador cliente. Esto se hace de la siguiente manera:

<?php
// Define la fecha de expiración a una hora antes de la fecha actual
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>

Ejemplo #3 setcookie() y los arrays

También puede utilizar cookies con arrays, utilizando la notación de arrays. Esto tiene el efecto de crear tantas cookies como elementos tenga su array, pero cuando las cookies sean recibidas por su script, los valores serán colocados en un array:

<?php
// Define las cookies
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// Después del recargado de la página, las mostramos
if (isset($_COOKIE['cookie'])) {
foreach (
$_COOKIE['cookie'] as $name => $value) {
$name = htmlspecialchars($name);
$value = htmlspecialchars($value);
echo
"$name : $value <br />\n";
}
}
?>

El resultado del ejemplo sería:

three : cookiethree
two : cookietwo
one : cookieone

Nota: El uso de caracteres de separación como [ y ] como parte del nombre de la cookie no es respetuoso con la RFC 6265, sección 4, pero se asume que es soportado por los agentes de usuario, siguiendo la RFC 6265, sección 5.

Notas

Nota:

Puede utilizar un buffer de salida para poder enviar contenido antes de llamar a esta función, con la contrapartida de que toda su página será enviada de una vez. Puede hacer esto llamando a ob_start() y ob_end_flush() en su script, o activando la directiva output_buffering en su archivo de configuración php.ini o en el archivo de configuración de su servidor.

Errores comunes:

  • Las cookies solo serán accesibles al cargar la próxima página, o al recargar la página actual. Para probar si una cookie ha sido definida con éxito, verifique la presencia de la cookie en el próximo cargado de página antes de que la cookie expire. El tiempo de expiración se define utilizando el argumento expires_or_options. Una forma sencilla de verificar el posicionamiento de la cookie es utilizar print_r($_COOKIE);.
  • Las cookies deben ser borradas con los mismos argumentos que los utilizados durante su creación. Si el argumento value es una cadena vacía y los otros argumentos son exactamente los mismos que en una llamada setcookie() previa, entonces la cookie será borrada del cliente. Internamente, el borrado se realiza posicionando el valor a 'deleted' y la fecha de expiración a un año en el pasado.
  • Dado que la asignación de un valor valiendo false a una cookie intenta borrarla, no se debe utilizar un booléen. En su lugar, utilice 0 para false y 1 para true.
  • Los nombres de las cookies pueden ser arrays de nombres y estarán disponibles en sus scripts PHP en forma de arrays, pero cookies diferentes serán colocadas en el cliente. Utilice explode() para colocar una cookie con nombres y valores múltiples. No se recomienda utilizar la función serialize() para hacer esto, ya que puede llevar a problemas de seguridad.

Las llamadas múltiples a la función setcookie() se realizarán en orden.

Ver también

add a note

User Contributed Notes 13 notes

up
397
walterquez
12 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
275
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
4 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
18 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
42
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
10 months 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
17
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
8
ellert at vankoperen dot nl
10 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
8
synnus at gmail dot com
4 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
4
Anonymous
14 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
steven at sovstack dot com
5 months 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