Função PHP setrawcookie(): Tudo o Que Você Precisa Saber

Como desenvolvedor PHP, pode ser necessário definir cookies brutos em sua aplicação web para armazenar informações no lado do cliente. A função setrawcookie() é uma função PHP embutida que permite definir um cookie bruto. Ao contrário da função padrão setcookie(), a setrawcookie() não codifica o valor do cookie por URL, tornando-a útil quando é necessário armazenar dados pré-codificados ou strings binárias. Neste artigo, analisaremos em profundidade a função setrawcookie() — sua sintaxe, parâmetros, a forma moderna com array de opções, armadilhas comuns e como ela difere de setcookie().

Esta página pressupõe que você já compreende os fundamentos dos cookies PHP. Se você simplesmente deseja armazenar texto comum, setcookie() costuma ser a melhor escolha — use setrawcookie() apenas quando precisar enviar o valor exatamente como está.

O que é a Função setrawcookie()?

A função setrawcookie() é uma função embutida do PHP (disponível desde o PHP 5.2.0) que permite definir um cookie bruto no lado do cliente. Ela funciona adicionando um cabeçalho de resposta HTTP Set-Cookie, portanto — como qualquer função que emite cabeçalhos — deve ser chamada antes de qualquer saída ser enviada ao navegador (sem HTML ecoado, sem linhas em branco antes de <?php, sem BOM). Se a saída já tiver sido iniciada, o cabeçalho é descartado silenciosamente. Consulte headers_sent() para saber como detectar isso.

A função retorna true se o cabeçalho foi enfileirado com sucesso e false em caso de falha. Observe que um retorno true não garante que o navegador aceitou ou enviará de volta o cookie — significa apenas que o cabeçalho foi emitido.

Como Usar a Função setrawcookie()

Usar a função setrawcookie() é simples. Veja a sintaxe:

Sintaxe PHP

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

A função aceita sete parâmetros:

• $name: O nome do cookie.
• $value: O valor bruto do cookie (sem codificação URL).
• $expire: O tempo de expiração como um timestamp Unix.
• $path: O caminho do servidor onde o cookie estará disponível.
• $domain: O domínio onde o cookie estará disponível.
• $secure: Se o cookie deve ser transmitido apenas via HTTPS.
• $httponly: Se o cookie deve ser inacessível ao JavaScript do lado do cliente.

Veja um exemplo de como usar a função setrawcookie() para definir um cookie bruto:

Exemplo

<?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);

Neste exemplo, usamos a função setrawcookie() para definir um cookie bruto chamado username com o valor john. Especificamos o tempo de expiração como 30 dias a partir do momento atual (usando time() como base), o caminho do servidor como / e o domínio como .example.com. Os flags secure e httponly são definidos como true para garantir que o cookie seja transmitido apenas via HTTPS e inacessível ao JavaScript do lado do cliente.

A assinatura com array de opções (PHP 7.3+)

Desde o PHP 7.3, é possível passar um único array $options em vez de argumentos posicionais. Esta é a forma recomendada porque é a única maneira de definir o atributo SameSite, que controla se o cookie é enviado em requisições entre sites:

<?php

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

Ao usar a forma de array, a chave $expire é chamada de expires (com s), e samesite não tem equivalente na assinatura posicional.

Lendo o cookie de volta

Um cookie definido em uma requisição não está disponível em $_COOKIE até que o navegador o envie de volta em uma requisição subsequente. Nessa requisição posterior, você o lê como qualquer outro cookie:

<?php

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

Como setrawcookie() não codifica o valor, os bytes que você armazenou são retornados exatamente como estão — não há etapa automática de urldecode() na leitura.

Excluindo um cookie bruto

Para remover um cookie, defina-o novamente com um tempo de expiração no passado. O name, path e domain devem coincidir com o cookie original:

<?php

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

setrawcookie() vs setcookie()

A principal diferença entre setcookie() e setrawcookie() é como elas tratam o valor do cookie. A setcookie() codifica automaticamente o valor por URL usando rawurlencode(), o que é seguro para texto padrão, mas pode causar problemas se você precisar armazenar dados pré-codificados ou strings binárias. A setrawcookie() ignora esta etapa de codificação, dando a você controle total sobre o valor bruto. Para a maioria dos casos de uso padrão, setcookie() é preferida, mas setrawcookie() é essencial quando se trabalha com dados já codificados.

Uma consequência prática: com setrawcookie(), você é responsável por manter o valor seguro para cookies. Um valor de cookie bruto não deve conter certos caracteres — caracteres de controle, espaços em branco, vírgulas, ponto e vírgulas ou sinais de igual — porque eles têm significado especial no cabeçalho Set-Cookie. Se o seu valor puder conter esses caracteres, codifique-o você mesmo (por exemplo, com rawurlencode()) antes de passá-lo:

<?php

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

Conclusão

A função setrawcookie() é uma ferramenta útil para definir cookies brutos em sua aplicação web PHP. Ao compreender sua sintaxe, parâmetros, a forma com array de opções e como ela difere de setcookie(), você pode armazenar dados pré-codificados com segurança no lado do cliente. Lembre-se de chamá-la antes de qualquer saída, prefira o array de opções para poder definir SameSite e use-a apenas quando realmente precisar contornar a codificação URL.

Tópicos relacionados

• Cookies PHP — o panorama geral de como os cookies funcionam no PHP.
• setcookie() — o definidor de cookies padrão com codificação URL.
• Sessões PHP — estado do lado do servidor, uma alternativa aos cookies.
• header() — enviar cabeçalhos HTTP arbitrários manualmente.
• headers_sent() — verificar se os cabeçalhos já foram enviados.

Prática