ToWebs

Descripción

bool setcookie ( string nombre [, string valor [, int expirar [, string ruta [, string dominio [, bool segura]]]]] )

setcookie() define una cookie para ser enviada junto con el resto de las cabeceras HTTP. Como otras cabeceras, las cookies deben ser enviadas antes de cualquier salida desde su script (esta es una restricción de protocolo). Esto requiere que coloque las llamadas a esta función antes de cualquier salida, incluyendo las etiquetas <html> y <head> así como cualquier espacio en blanco. Si existe salida antes de llamar esta función, setcookie() fallará y devolverá FALSE. Si setcookie() se ejecuta con éxito, devolverá TRUE. Esto no indica si el usuario aceptó la cookie.

Nota: A partir de PHP 4, es posible usar control de búferes para producir salida antes de llamar esta función, con cierta penalización en rendimiento debido a que la salida al navegador es almacenada en el servidor hasta ser enviada. Es posible hacerlo llamando a ob_start() y ob_end_flush() en su script, o definiendo la directiva de configuración output_buffering en su archivo php.ini o en los archivos de configuración del servidor.

Todos los argumentos con excepción de nombre son opcionales. Es posible también reemplazar un argumento con una cadena vacía ("") para evitar ese argumento. Dado que el argumento expirar es entero, no puede saltarse con una cadena vacía, use un cero (0) en su lugar. La siguiente tabla explica cada parámetro de la función setcookie(), asegúrese de leer la especificación de cookies de Netscape para conocer los detalles sobre cómo funciona cada parámetro de setcookie() y el documento RFC 2965 para más información sobre cómo trabajan las cookies HTTP.

Tabla 1. Los parámetros de setcookie() explicados

Parámetro	Descripción	Ejemplos
`nombre`	El nombre de la cookie.	'nombre_cookie' es llamada como `$_COOKIE['nombre_cookie']`
`valor`	El valor de la cookie. Este valor es almacenado en el equipo del cliente; no almecene información sensible.	Asumiendo que `nombre` es 'nombre_cookie', este valor es recuperado por medio de `$_COOKIE['nombre_cookie']`
`expirar`	La hora en la que expira la cookie. Este valor es una marca de tiempo Unix así que es el número de segundos recorridos desde el epoch. En otras palabras, es probable que este valor sea definido con la función time() más el número de segundos antes de que usted quiera que expire. O es posible usar mktime().	`time()+606024*30` definirá que la cookie expire en 30 días. Si no se define, la cookie expirará al final de la sesión (cuando el navegador sea cerrado).
`ruta`	La ruta en el servidor en la que estará disponible la cookie.	Si se define como `'/'`, la cookie estará disponible en el `dominio` completo. Si se define como `'/foo/'`, la cookie estará disponible únicamente al interior del directorio `/foo/` y todos sus subdirectorios en `dominio` como `/foo/bar/`. El valor predeterminado es el directorio actual en el que se define la cookie.
`dominio`	El dominio en el que la cookie está disponible.	Para lograr que la cookie esté disponible en todos los subdominios de example.com entonces es necesario definir este valor como `'.example.com'`. El caracter `.` no es requerido pero hace a la cookie compatible con más navegadores. Definir su valor como `www.example.com` hará que la cookie esté disponible únicamente en el subdominio `www`. Refiérase a la comparación de sufijos en la especificación para más detalles.
`segura`	Indica que la cookie debería ser transmitida únicamente sobre una conexión HTTPS segura. Cuando su valor es `TRUE`, la cookie será definida únicamente si existe una conexión segura. El valor predeterminado es `FALSE`.	`0` o `1`

Una vez se han definido las cookies, ellas pueden ser accesadas en la siguiente carga de página con las matrices $_COOKIE o $HTTP_COOKIE_VARS. Note que las variables auto-globales como $_COOKIE aparecieron en PHP 4.1.0. $HTTP_COOKIE_VARS ha existido desde PHP 3. Los valores de cookies también existen en $_REQUEST.

Nota: Si la directiva register_globals está definida como on entonces los valores de cookie también serán registrados como variables. En nuestros ejemplos siguientes, la variable $CookieDePrueba existirá. Es recomendable usar $_COOKIE.

Errores Comunes:

Las cookies no serán visibles hasta la siguiente carga de una página en la que debe estar disponible la cookie. Para probar si una cookie ha sido definida exitosamente, verifique la cookie en una carga de página siguiente antes de que la cookie expire. El tiempo de expiración es definido mediante el parámetro expirar. Una forma adecuada para depurar la existencia de cookies es simplemente llamando print_r($_COOKIE);.
Las cookies deben ser eliminadas con los mismos parámetros con los que son creadas. Si el argumento valor es una cadena vacía, o FALSE, y todos los demás argumentos coinciden con una llamada previa a setcookie, entonces la cookie cen el nombre especificado será eliminada del cliente remoto.
Ya que la definición de una cookie con un valor de FALSE intentará eliminar la cookie, no deberían usarse valores booleanos. En su lugar, use 0 para FALSE y 1 para TRUE.
Los nombres de cookie pueden ser definidos como nombres de matrices y estarán disponibles en sus scripts PHP como matrices, pero en el sistema del usuario se almacenan cookies separadas. Considere el uso de explode() para definir una cookie con múltiples nombres y valores. No es recomendable usar serialize() para este propósito, ya que puede resultar en agujeros de seguridad.

En PHP 3, múltiples llamadas a setcookie() en el mismo script serán efectuadas en el orden inverso. Si se intenta eliminar una cookie antes de insertar otra, es necesario colocar la inserción antes de la eliminación. A partir de PHP 4, múltiples llamadas a setcookie() son realizadas en el orden de llamado.

A continuación se presentan algunos ejemplos sobre cómo enviar cookies:

Ejemplo 1. Ejemplo de envío de setcookie()


<?php
$valor = 'algo desde algun lugar';

setcookie("CookieDePrueba", $valor);
setcookie("CookieDePrueba", $valor, time()+3600);  /* expirar en 1 hora */
setcookie("CookieDePrueba", $valor, time()+3600, "/~rasmus/", ".example.com", 1);
?>

Note que la porción del valor de la cookie será codificado (mediante urlencode) automáticamente cuando envíe la cookie, y que al ser recibida la cookie, es automáticamente decodificada y asignada a una variable con el mismo nombre que la cookie. Si no desea esto, puede usar setrawcookie() en su lugar, si está usando PHP 5. Para ver los contenidos de nuestra cookie de prueba en un script, simplemente use uno de los siguientes ejemplos:


<?php
// Imprime una cookie individual
echo $_COOKIE["CookieDePrueba"];
echo $HTTP_COOKIE_VARS["CookieDePrueba"];

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

Al eliminar una cookie, es buena idea asegurarse de que la fecha de expiración sea en el pasado, para activar el mecanismo de eliminación en su navegador. Los siguientes ejemplos demuestran cómo eliminar cookies enviadas en el ejemplo anterior:

Ejemplo 2. Ejemplo de eliminación de setcookie()


<?php
// establecer la fecha de expiracion hace una hora
setcookie ("CookieDePrueba", "", time() - 3600);
setcookie ("CookieDePrueba", "", time() - 3600, "/~rasmus/", ".example.com", 1);
?>

También es posible definir cookies tipo matriz usando una notación de matriz en el nombre de la cookie. Esto tiene el efecto de definir tantas cookies como elementos tenga la matriz, pero cuando la cookie es recibida por su script, los valores son todos colocados en una matriz con el nombre de la cookie:

Ejemplo 3. setcookie() y matrices


<?php
// definir las cookies
setcookie("cookie[tres]", "cookietres");
setcookie("cookie[dos]", "cookiedos");
setcookie("cookie[uno]", "cookieuno");

// luego de que la pagina recarga, imprimirlas
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $nombre => $valor) {
        echo "$nombre : $valor <br />\n";
    }
}
?>

lo cual imprime

tres : cookietres
dos : cookiedos
uno : cookieuno

Nota: Los siguientes documentos RFC pueden resultar útiles también: RFC 2109 y RFC 2695
Puede que haya notado que el parámetro expirar recibe una marca de tiempo Unix, en lugar del formato de fecha Dia, DD-Mes-YYYY HH:MM:SS GMT, esto se debe a que PHP realiza esta conversión internamente.
expirar es comparado con la hora del cliente, la cual puede diferir de la hora del servidor.

Nota: Microsoft Internet Explorer 4 con el Service Pack 1 aplicado no maneja correctamente las cookies que tienen su parámetro de ruta definido.
Parece que Netscape Communicator 4.05 y Microsoft Internet Explorer 3.x manejan las cookies incorrectamente cuando la ruta y hora no son definidas.

Vea también header(), setrawcookie() y la sección sobre cookies.