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

Como desarrollador PHP, es posible que necesites establecer cookies sin procesar en tu aplicación web para almacenar información en el lado del cliente. La función setrawcookie() es una función integrada de PHP que te permite establecer una cookie sin procesar. A diferencia de la función estándar setcookie(), setrawcookie() no codifica el valor de la cookie con URL-encode, lo que la hace útil cuando necesitas almacenar datos precodificados o cadenas binarias. En este artículo, analizaremos en detalle la función setrawcookie(): su sintaxis, parámetros, la forma moderna con array de opciones, los errores comunes y en qué se diferencia de setcookie().

Esta página presupone que ya comprendes los conceptos básicos de las cookies PHP. Si simplemente deseas almacenar texto ordinario, setcookie() suele ser la mejor opción; recurre a setrawcookie() solo cuando necesites enviar el valor exactamente tal como está.

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

La función setrawcookie() es una función integrada de PHP (disponible desde PHP 5.2.0) que te permite establecer una cookie sin procesar en el lado del cliente. Funciona añadiendo una cabecera HTTP de respuesta Set-Cookie, por lo que, como toda función que emite cabeceras, debe llamarse antes de que se envíe cualquier salida al navegador (sin HTML impreso, sin líneas en blanco antes de <?php, sin BOM). Si la salida ya ha comenzado, la cabecera se descarta silenciosamente. Consulta headers_sent() para saber cómo detectar esto.

La función devuelve true si la cabecera se puso en cola correctamente y false en caso de error. Ten en cuenta que un retorno true no garantiza que el navegador haya aceptado o vaya a devolver la cookie: solo significa que la cabecera fue emitida.

Cómo usar la función setrawcookie()

Usar la función setrawcookie() es sencillo. Esta es la sintaxis:

Sintaxis PHP

setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

La función acepta siete parámetros:

• $name: El nombre de la cookie.
• $value: El valor sin procesar de la cookie (sin codificación URL).
• $expire: El tiempo de expiración como marca de tiempo Unix.
• $path: La ruta del servidor donde estará disponible la cookie.
• $domain: El dominio donde estará disponible la cookie.
• $secure: Si la cookie solo debe transmitirse a través de HTTPS.
• $httponly: Si la cookie debe ser inaccesible para JavaScript del lado del cliente.

Aquí tienes un ejemplo de cómo usar la función setrawcookie() para establecer una cookie sin procesar:

Ejemplo

<?php

$name = "username";
$value = "john";
$expire = time() + (86400 * 30); // 30 days
$path = "/";
$domain = ".example.com";
$secure = true;
$httponly = true;
setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

En este ejemplo, usamos la función setrawcookie() para establecer una cookie sin procesar llamada username con el valor john. Especificamos el tiempo de expiración como 30 días a partir del momento actual (usando time() como base), la ruta del servidor como / y el dominio como .example.com. Los indicadores secure y httponly se establecen en true para garantizar que la cookie solo se transmita a través de HTTPS y sea inaccesible para JavaScript del lado del cliente.

La firma con array de opciones (PHP 7.3+)

Desde PHP 7.3 puedes pasar un único array $options en lugar de argumentos posicionales. Esta es la forma recomendada porque es la única manera de establecer el atributo SameSite, que controla si la cookie se envía en solicitudes entre sitios:

<?php

setrawcookie("username", "john", [
    "expires"  => time() + (86400 * 30), // 30 days
    "path"     => "/",
    "domain"   => ".example.com",
    "secure"   => true,
    "httponly" => true,
    "samesite" => "Strict", // "Strict", "Lax", or "None"
]);

Al usar la forma de array, la clave $expire se denomina expires (con s), y samesite no tiene equivalente en la firma posicional.

Leer la cookie de vuelta

Una cookie establecida en una solicitud no está disponible en $_COOKIE hasta que el navegador la devuelva en una solicitud posterior. En esa solicitud posterior la lees como cualquier otra cookie:

<?php

if (isset($_COOKIE["username"])) {
    echo "Welcome back, " . $_COOKIE["username"];
} else {
    echo "Cookie not set yet.";
}

Dado que setrawcookie() no codifica el valor, los bytes que almacenaste se devuelven exactamente tal como están: no hay un paso automático de urldecode() al leerlos de vuelta.

Eliminar una cookie sin procesar

Para eliminar una cookie, establécela de nuevo con un tiempo de expiración en el pasado. El name, path y domain deben coincidir con la cookie original:

<?php

setrawcookie("username", "", time() - 3600, "/", ".example.com");

setrawcookie() vs setcookie()

La principal diferencia entre setcookie() y setrawcookie() es cómo gestionan el valor de la cookie. setcookie() codifica automáticamente el valor con URL-encode usando rawurlencode(), lo cual es seguro para texto estándar pero puede causar problemas si necesitas almacenar datos precodificados o cadenas binarias. setrawcookie() omite este paso de codificación, dándote control total sobre el valor sin procesar. Para la mayoría de los casos de uso estándar se prefiere setcookie(), pero setrawcookie() es esencial cuando trabajas con datos ya codificados.

Una consecuencia práctica: con setrawcookie() eres responsable de mantener el valor compatible con las cookies. El valor de una cookie sin procesar no debe contener ciertos caracteres: caracteres de control, espacios en blanco, comas, punto y coma o signos de igual, porque tienen un significado especial en la cabecera Set-Cookie. Si tu valor puede contener esos caracteres, codifícalo tú mismo (por ejemplo con rawurlencode()) antes de pasarlo:

<?php

$raw = rawurlencode("john doe; admin=1"); // pre-encode unsafe bytes
setrawcookie("username", $raw, time() + 3600, "/");

Conclusión

La función setrawcookie() es una herramienta útil para establecer cookies sin procesar en tu aplicación web PHP. Al comprender su sintaxis, parámetros, la forma con array de opciones y en qué se diferencia de setcookie(), puedes almacenar de forma segura datos precodificados en el lado del cliente. Recuerda llamarla antes de cualquier salida, preferir el array de opciones para poder establecer SameSite, y recurrir a ella solo cuando genuinamente necesites omitir la codificación URL.

Temas relacionados

• Cookies PHP: el panorama general de cómo funcionan las cookies en PHP.
• setcookie(): el setter de cookies estándar con codificación URL.
• Sesiones PHP: estado del lado del servidor, una alternativa a las cookies.
• header(): enviar cabeceras HTTP arbitrarias manualmente.
• headers_sent(): comprobar si las cabeceras ya han sido enviadas.

Práctica