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

Como desenvolvedor PHP, você pode precisar definir cookies para armazenar informações no lado do cliente. A função setcookie() é uma função integrada do PHP que cuida disso. Neste artigo, abordamos sua sintaxe moderna, como definir, ler e excluir cookies, os erros mais comuns e quando usar sessões em vez de cookies.

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

A função setcookie() é uma função integrada do PHP que envia um cabeçalho HTTP Set-Cookie ao navegador, solicitando que ele armazene um pequeno dado. Na próxima requisição, o navegador envia esse dado de volta, que é como um protocolo sem estado como HTTP pode "lembrar" coisas entre carregamentos de página — por exemplo, um token de "lembrar-me", uma preferência de idioma ou um ID de rastreamento.

Como um cookie é um cabeçalho HTTP, a função setcookie() deve ser executada antes de qualquer saída ser enviada ao navegador. O cookie em si não fica disponível imediatamente; ele aparece no superglobal $_COOKIE somente na próxima requisição, quando o navegador o envia de volta.

Como Usar a Função setcookie()

O uso da função setcookie() é simples. A sintaxe baseada em array de opções foi introduzida no PHP 7.3. No PHP 8.1, a sintaxe posicional de sete parâmetros legada foi descontinuada. Esta é a sintaxe moderna:

A sintaxe PHP da Função setcookie()

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

O parâmetro $options é um array associativo que aceita as seguintes chaves:

• expires: O tempo de expiração do cookie (timestamp Unix).
• path: O caminho no servidor em que o cookie estará disponível.
• domain: O domínio em que o cookie estará disponível.
• secure: Se o cookie deve ser transmitido apenas via HTTPS.
• httponly: Se o cookie deve ser acessível apenas via HTTP.
• samesite: Restringe o cookie a requisições do mesmo site. Aceita 'Strict', 'Lax' ou 'None'. Nota: ao usar 'None', você também deve definir secure como true, ou os navegadores modernos rejeitarão o cookie.

Se você omitir expires (ou defini-lo como 0), o cookie se tornará um cookie de sessão — ele dura apenas até o navegador ser fechado. Definir expires com um timestamp futuro o transforma em um cookie persistente que sobrevive a reinicializações do navegador.

Aqui está um exemplo de como usar a função setcookie() para definir um cookie:

Como Usar a Função setcookie()?

<?php

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

Neste exemplo, usamos a função setcookie() para definir um cookie chamado username com o valor john. Também especificamos o tempo de expiração como 30 dias a partir do momento atual, o caminho no servidor como /, o domínio como .example.com, e definimos os flags secure, httponly e samesite para garantir que o cookie seja transmitido apenas via HTTPS, não seja acessível via scripts do lado do cliente e seja restrito a requisições do mesmo site, respectivamente.

Lendo Cookies

Os cookies definidos com setcookie() ficam automaticamente disponíveis no array superglobal $_COOKIE nas requisições de página subsequentes. Você pode verificar sua existência e ler seus valores assim:

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

Excluindo Cookies

Para excluir um cookie, você deve definir seu tempo de expiração para um timestamp passado. O valor pode ser deixado vazio.

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

Certifique-se de que o path (e o domain, se você definiu um) correspondam aos valores usados ao criar o cookie. Um cookie definido com path => '/admin' não será excluído por uma chamada que usa path => '/', porque o navegador os trata como cookies diferentes.

Notas Importantes

• Valor de Retorno: setcookie() retorna true em caso de sucesso e false em caso de falha (inclusive quando os cabeçalhos já foram enviados).
• Cabeçalhos Já Enviados: Os cookies devem ser definidos antes de qualquer saída ser enviada ao navegador (incluindo HTML, espaços em branco antes de <?php ou echo). Caso contrário, o PHP lançará um aviso de "Headers already sent". Veja headers_sent() para detectar esse caso.
• Codificação Automática: setcookie() codifica automaticamente os valores dos cookies via URL, portanto a codificação manual geralmente é desnecessária. Se você precisar armazenar um valor literalmente sem codificação, use setrawcookie() em vez disso.
• Limites de Tamanho: Os navegadores limitam cada cookie a aproximadamente 4 KB e restringem quantos cookies um único domínio pode armazenar, portanto os cookies são destinados a valores pequenos, não a dados em massa.

Cookies vs. Sessões

Os cookies residem no navegador e são enviados com cada requisição, portanto qualquer coisa que você armazene é visível (e editável) pelo usuário. Para dados sensíveis, armazene apenas um identificador no cookie e mantenha os dados reais no lado do servidor com sessões PHP. Para uma visão geral mais ampla do tratamento de cookies em PHP, consulte o capítulo Cookies PHP.

Conclusão

A função setcookie() é uma ferramenta útil para definir cookies em sua aplicação web PHP. Ao entender a sintaxe moderna de array, executá-la antes de qualquer saída e corresponder path/domain ao excluir, você pode gerenciar de forma confiável os dados do lado do cliente — e saber quando usar sessões em vez disso.

Prática