Función PHP setcookie(): Todo lo que necesitas saber

Como desarrollador PHP, puede que necesites establecer cookies para almacenar información en el lado del cliente. La función setcookie() es una función integrada de PHP que se encarga de esto. En este artículo, cubrimos su sintaxis moderna, cómo establecer, leer y eliminar cookies, los errores más comunes y cuándo usar sesiones en su lugar.

¿Qué es la función setcookie()?

La función setcookie() es una función integrada de PHP que envía una cabecera HTTP Set-Cookie al navegador, pidiéndole que almacene un pequeño fragmento de datos. En la siguiente solicitud, el navegador devuelve esos datos, lo que permite que un protocolo sin estado como HTTP pueda "recordar" cosas entre cargas de página — por ejemplo, un token de "recuérdame", una preferencia de idioma o un ID de seguimiento.

Dado que una cookie es una cabecera HTTP, setcookie() debe ejecutarse antes de que se envíe cualquier salida al navegador. La propia cookie no está disponible de inmediato; aparece en el superglobal $_COOKIE solo en la siguiente solicitud, una vez que el navegador la haya enviado de vuelta.

Cómo usar la función setcookie()

Usar la función setcookie() es sencillo. La sintaxis de opciones basada en array fue introducida en PHP 7.3. En PHP 8.1, la sintaxis posicional de siete parámetros heredada fue marcada como obsoleta. Esta es la sintaxis moderna:

La sintaxis PHP de la función setcookie()

setcookie($name, $value, $options);

El parámetro $options es un array asociativo que acepta las siguientes claves:

• expires: El tiempo de expiración de la cookie (marca de tiempo Unix).
• path: La ruta en el servidor en la que la cookie estará disponible.
• domain: El dominio en el que la cookie estará disponible.
• secure: Si la cookie debe transmitirse solo a través de HTTPS.
• httponly: Si la cookie debe ser accesible solo a través de HTTP.
• samesite: Restringe la cookie a solicitudes del mismo sitio. Acepta 'Strict', 'Lax' o 'None'. Nota: cuando usas 'None', también debes establecer secure en true, o los navegadores modernos rechazarán la cookie.

Si omites expires (o lo estableces en 0), la cookie se convierte en una cookie de sesión — solo existe hasta que se cierre el navegador. Establecer expires en una marca de tiempo futura la convierte en una cookie persistente que sobrevive a los reinicios del navegador.

Aquí hay un ejemplo de cómo usar la función setcookie() para establecer una cookie:

¿Cómo usar la función setcookie()?

<?php

$options = [
    'expires'  => time() + (86400 * 30), // 30 days
    'path'     => '/',
    'domain'   => '.example.com',
    'secure'   => true,
    'httponly' => true,
    'samesite' => 'Lax'
];
setcookie('username', 'john', $options);

En este ejemplo, usamos la función setcookie() para establecer una cookie llamada username con el valor john. También especificamos el tiempo de expiración como 30 días a partir del momento actual, la ruta en el servidor como /, el dominio como .example.com, y establecemos las opciones secure, httponly y samesite para garantizar que la cookie solo se transmita a través de HTTPS, no sea accesible mediante scripts del lado del cliente y esté restringida a solicitudes del mismo sitio, respectivamente.

Lectura de cookies

Las cookies establecidas con setcookie() están disponibles automáticamente en el array superglobal $_COOKIE en las solicitudes de página posteriores. Puedes verificar su existencia y leer sus valores de la siguiente manera:

if (isset($_COOKIE['username'])) {
    echo "Welcome, " . htmlspecialchars($_COOKIE['username']);
}

Eliminación de cookies

Para eliminar una cookie, debes establecer su tiempo de expiración en una marca de tiempo pasada. El valor puede dejarse vacío.

setcookie('username', '', [
    'expires' => time() - 3600,
    'path'    => '/',
]);

Asegúrate de que path (y domain, si lo estableciste) coincidan con los valores que usaste al crear la cookie. Una cookie establecida con path => '/admin' no será eliminada por una llamada que use path => '/', porque el navegador las trata como cookies diferentes.

Notas importantes

• Valor de retorno: setcookie() devuelve true si tiene éxito y false si falla (incluyendo cuando las cabeceras ya han sido enviadas).
• Cabeceras ya enviadas: Las cookies deben establecerse antes de que se envíe cualquier salida al navegador (incluido HTML, espacios en blanco antes de <?php o echo). De lo contrario, PHP lanzará una advertencia de "Headers already sent". Consulta headers_sent() para detectar este caso.
• Codificación automática: setcookie() codifica automáticamente los valores de las cookies con URL encoding, por lo que la codificación manual generalmente no es necesaria. Si necesitas almacenar un valor textualmente sin codificación, usa setrawcookie() en su lugar.
• Límites de tamaño: Los navegadores limitan cada cookie a aproximadamente 4 KB y restringen cuántas cookies puede almacenar un único dominio, por lo que las cookies están pensadas para valores pequeños, no para datos masivos.

Cookies vs. Sesiones

Las cookies viven en el navegador y se envían con cada solicitud, por lo que cualquier cosa que almacenes es visible (y editable) por el usuario. Para datos sensibles, almacena solo un identificador en la cookie y guarda los datos reales en el servidor con sesiones PHP. Para una visión más amplia del manejo de cookies en PHP, consulta el capítulo de Cookies PHP.

Conclusión

La función setcookie() es una herramienta útil para establecer cookies en tu aplicación web PHP. Al comprender la sintaxis moderna de array, ejecutarla antes de cualquier salida y hacer coincidir path/domain al eliminar, puedes gestionar de forma fiable los datos del lado del cliente, y sabrás cuándo usar sesiones en su lugar.

Práctica