(PHP 4, PHP 5, PHP 7)
setcookie — Enviar una cookie
$name
[, string $value = ""
[, int $expires = 0
[, string $path = ""
[, string $domain = ""
[, bool $secure = FALSE
[, bool $httponly = FALSE
]]]]]] ) : bool$name
[, string $value = ""
[, array $options = []
]] ) : boolsetcookie() define una cookie para ser enviada junto con el resto de cabeceras HTTP. Como otros encabezados, cookies deben ser enviadas antes de cualquier salida en el script (este es un protocolo de restricción). Esto requiere que hagas llamadas a esta función antes de cualquier salida, incluyendo etiquetas <html> y <head> así como cualquier espacio en blanco.
Una vez que las cookies se han establecido, se puede acceder a ellas en la siguiente página de carga con el array $_COOKIE. valores Cookie también pueden existir en $_REQUEST.
» RFC 6265 proporciona la referencia normativa como cada parámetro setcookie() es interpretado.
nameEl nombre de la cookie.
value
El valor de la cookie. Este valor se almacena en el ordenador del cliente;
no almacenar información sensible. Asumiendo que el
name es 'cookiename', este
valor es recuperado a través de $_COOKIE['cookiename']
expiresEl tiempo en que la cookie expira. Esta es una marca de tiempo Unix en número de segundos desde la época. En otras palabras, lo más probable es que se haga con la función time() más el número de segundos antes de que quiera que expire. O se podría usar mktime(). time()+60*60*24*30 hará que la cookie establecida expire en 30 días. Si se establece a 0, o es omitido, la cookie expirará al final de la sesión (cuando el navegador es cerrado).
Nota:
Puede notar que el parámetro
expirestoma una marca de tiempo Unix, en lugar de formato de fecha Wdy, DD-Mon-YYYY HH:MM:SS GMT, esto es porque PHP hace la conversión internamente.
path
La ruta dentro del servidor en la que la cookie estará disponible.
Si se utiliza '/', la cookie estará disponible
en la totalidad del domain. Si se configura
como '/foo/', la cookie sólo estará disponible
dentro del directorio /foo/ y todos sus
sub-directorios en el domain, tales como
/foo/bar/. El valor por defecto es el
directorio actual en donde se está configurando la cookie.
domainEl (sub)dominio al que la cookie está disponible. Estableciendo esto a un subdominio (como 'www.example.com') hará que la cookie esté disponible para ese subdominio y todos los demás subdominios del mismo (p.e. w2.www.example.com). Para que la cookie esté disponible para todo el dominio (incluyendo todos sus subdominios), simplemente establezca el nombre de domonio ('example.com', en este caso).
Los navegadores más antiguos todavía implementan la obsoleta » RFC 2109 pueden necesitar un . para comparar todos los subdominios.
secure
Indica que la cookie sólo debiera transmitirse por una
conexión segura HTTPS desde el cliente. Cuando se configura como TRUE,
la cookie sólo se creará si es que existe una conexión segura.
Del lado del servidor, depende del programador el enviar este
tipo de cookies solamente a través de conexiones seguras (por ejemplo,
con $_SERVER["HTTPS"]).
httponly
Cuando es TRUE la cookie será accesible sólo a través del protocolo
HTTP. Esto significa que la cookie no será accesible por lenguajes
de scripting, como JavaScript. Se ha indicado que esta configuración
ayuda efectivamente a reducir el robo de identidad a través de ataques XSS (aunque no
es soportada por todos los navegadores). pero esa afirmación se disputa a menudo. Agregado en PHP 5.2.0.
Puede ser TRUE o FALSE
optionsUn array asociativo que puede tener cualquiera de las claves expires, path, domain, secure, httponly y samesite. Los valores tienen el mismo significado que se describe para los parámetros con el mismo nombre. El valor de el elemento samesite debería ser None, Lax o Strict. Si no se da ninguna de las opciones permitidas, sus valores por defecto son los mismos que los valores por defecto de los parámetros explícitos. Si el elemento samesite es omitido, no se establece ningún atributo de la cookie SameSite.
Si existe algún tipo de output anterior a la llamada de esta función,
setcookie() fallará y retornará FALSE. Si
setcookie() ejecuta satisfactoriamente, retornará TRUE.
Esto no indica si es que el usuario ha aceptado la cookie o no.
A continuación se presentan algunos ejemplos de cómo enviar cookies:
Ejemplo #1 Ejemplo de envío con setcookie()
<?php
$value = 'something from somewhere';
setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600); /* expira en 1 hora */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", 1);
?>
Nótese que la parte del valor de la cookie será automáticamente codificada con urlencode al enviar la cookie, y al ser recibida será automáticamente decodificada y asignada a una variable con el mismo nombre que el nombre de la cookie. Si no se desea ésto, se puede usar setrawcookie() si es que se está utilizando PHP 5. Para ver el contenido de nuestra cookie de prueba en un script, simplemente siga uno de los ejemplo siguientes:
<?php
// Imprime una cookie individual
echo $_COOKIE["TestCookie"];
// Otra forma de depurar/prueba es ver todas las cookies
print_r($_COOKIE);
?>
Ejemplo #2 Ejemplo de eliminación con setcookie()
Al borrar una cookie debe asegurarse que la fecha de expiración ya ha pasado, de modo a detonar el mecanismo de eliminación del navegador. El siguiente ejemplo muestra cómo borrar las cookies enviadas en el ejemplo anterior:
<?php
// establecer la fecha de expiración a una hora atrás
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
Ejemplo #3 setcookie() y los arrays
También puede crear arrays de cookies utilizando la notación de arrays en el nombre de la cookie. El efecto de esto es de crear tantas cookies como elementos hay en el array, pero al recibir el script la cookie, todos los valores son colocados en un array con el nombre de la cookie:
<?php
// set the cookies
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");
// después de que la página se recargue, imprime
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
| Versión | Descripción |
|---|---|
| 7.3.0 |
Una alternativa que soporta un array options
ha sido añadida. Esta alternativa soporta también la configuración del atributo
de la cookie de SameSite.
|
| 5.5.0 | Ahora se incluye un atributo Max-Age en la cabecera Set-Cookie enviada al cliente. |
| 5.2.0 |
Se añadió el parámetro httponly.
|
Nota:
Se puede utilizar buffering de salida para enviar output anterior a la llamada a esta función, de modo que todo el output hacia el browser sea almacenado en el servidor hasta que lo envíe. Para hacer ésto invoque en su script a ob_start() y ob_end_flush(), o active la directiva de configuración output_buffering en el archivo php.ini o en los archivos de configuración del servidor.
Nota:
Si la directiva de PHP register_globals está en on los valores de las cookies también serán convertidos en variables. En el ejemplo de más abajo,$TestCookie existirá. Se recomienda simplemente utilizar $_COOKIE.
Common Pitfalls:
expires. Una forma sencilla de verificar
la existencia de cookies es invocando print_r($_COOKIE);.
FALSE, y todos los demás argumentos
coinciden con una llamada anterior a setcookie, entonces la cookie con el nombre
especificado será eliminada del cliente remoto.
Internamente ésto se logra estableciendo el valor a 'deleted' y el tiempo
de expiración a un año atrás.
FALSE intentará eliminar la cookie,
no se debieran utilizar valores booleanos. En su lugar, use 0 como FALSE
y 1 como TRUE.
Múltiples llamadas a setcookie() se efectúan en el orden de llamada.