(PHP 4, PHP 5, PHP 7, PHP 8)
setcookie — Envía una cookie
$name
,$value
= "",$expires_or_options
= 0,$path
= "",$domain
= "",$secure
= false
,$httponly
= false
Firma alternativa disponible a partir de PHP 7.3.0 (no soportado con parámetros nombrados):
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.
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 formatoDí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().
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.
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.
|
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.
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:
expires_or_options
.
Una forma sencilla de verificar el posicionamiento de la cookie es utilizar
print_r($_COOKIE);
.
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.
false
a una cookie
intenta borrarla, no se debe utilizar un booléen.
En su lugar, utilice 0 para false
y 1 para true
.
Las llamadas múltiples a la función setcookie() se realizarán en orden.