Enviar una cookie

Descripción

bool setcookie ( string $name [, string $value [, int $expire = 0 [, string $path [, string $domain [, bool $secure = false [, bool $httponly = false ]]]]]] )

setcookie() define una cookie para ser enviada junto con el resto de las cabeceras de HTTP. Al igual que otras cabeceras, las cookies deben ser enviadas antes de que el script genere ninguna salida (es una restricción del protocolo). Ésto implica que las llamadas a esta función se coloquen antes de que se genere cualquier salida, incluyendo las etiquetas <html> y <head> al igual que cualquier espacio en blanco.

Una vez que han sido enviadas las cookies, se puede acceder a ellas en la próxima carga de la página gracias a los arrays $_COOKIE o $HTTP_COOKIE_VARS. Nótese que las superglobales tales como $_COOKIE están disponibles a partir de PHP 4.1.0. El valor de las cookies también está en $_REQUEST.

Parámetros

Todos los argumentos exceptuando el argumento name son opcionales. También puede reemplazar un argumento con un string vacío ("") para saltárselo. Ya que el argumento expire es un entero, no puede pasarse por alto con un string vacío, en su lugar utilice un cero (0).

La referencia » RFC 6265 provee la normativa que establece cómo debe ser interpretado cada parámetro de setcookie().

name

El nombre de la cookie.

value

El valor de la cookie. Este valor se guarda en el computador del cliente; no almacene información sensible. Asumiendo que el name es 'cookiename', este valor se obtiene con $_COOKIE['cookiename'].

expire

El tiempo en el que expira la cookie. Es una fecha Unix por tanto está en número de segundos a partir de la presente época. En otras palabras, probablemente utilizará la función time() más el número de segundos que quiere que dure la cookie. También podría utilizar la función mktime(). time()+60*60*24*30 configurará la cookie para expirar en 30 días. Si se pone 0, o se omite, la cookie expirará al final de la sesión (al cerrarse el navegador).

Nota:
Puede notar que el parámetro expire recibe una fecha Unix, por oposición al formato de fecha Wdy, DD-Mon-YYYY HH:MM:SS GMT, esto se debe a que PHP realiza esta 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.

domain

El dominio para el cual la cookie está disponible. Establecer el dominio a 'www.example.com' hará que la cookie esté disponible en el subdominio www y subdominios superiores. Las cookies disponibles en un dominio inferior, como 'example.com', estarán disponibles en dominios superiores, como 'www.example.com'. Los navegadores antiguos que aún implementan la referencia obsoleta » RFC 2109 pueden necesitar un . al inicio 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

Valores devueltos

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.

Ejemplos

A continuación algunos ejemplos acerca de cómo enviar cookies:

Ejemplo #1 ejemplo de envío con setcookie()


<?php
$value = 'cualquier cosa';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);  /* expira en una 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
// Imprimir una cookie individual
echo $_COOKIE["TestCookie"];
echo $HTTP_COOKIE_VARS["TestCookie"];

//Otra manera de depurar/probar es viendo todas las cookies
print_r($_COOKIE);
?>

Ejemplo #2 ejemplo de borrado con setcookie()

Al borrar una cookie debiese 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 ésto 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
// crear las cookies
setcookie("cookie[tres]", "cookietres");
setcookie("cookie[dos]", "cookiedos");
setcookie("cookie[uno]", "cookieuno");

// imprimirlas luego que la página es recargada
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:

tres : cookietres
dos : cookiedos
uno : cookieuno

Historial de cambios

Versión	Descripción
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`.

Notas

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.

Trampas habituales:

Las cookies no se volverán visibles hasta la próxima carga de la página en la que debieran serlo. Para probar si se ha creado correctamente una cookie, se debe buscar la cookie en alguna página cargada posteriormente y antes que la cookie expire. El tiempo de expiración se establece con el parámetro expire. Una forma sencilla de verificar la existencia de cookies es invocando print_r($_COOKIE);.
Las cookies deben ser borradas usando los mismos parámetros con que fueron creadas. Si el argumento del valor es un string vacío o 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.
Ya que configurar el valor de una cookie como FALSE intentará eliminar la cookie, no se debieran utilizar valores booleanos. En su lugar, use 0 como FALSE y 1 como TRUE.
Los nombres de las cookies pueden declararse como nombres de arrays y estarán disponibles en sus scripts PHP como arrays, pero en el sistema del usuario se guardarán como cookies separadas. Considere la función explode() para crear una sola cookie con nombres y valores múltiples. No se recomienda utilizar la función serialize() para este propósito, pues puede significar vulnerabilidades en la seguridad.

Múltiples llamadas a setcookie() se efectúan en el orden de llamada.

Ver también

header() - Enviar encabezado sin formato HTTP
setrawcookie() - Enviar una cookie sin codificar su valor
sección sobre cookies
» RFC 6265
» RFC 2109