PHP Cookies

Cada pedido que chega ao PHP é um recomeço: o programa roda, responde e esquece tudo. Se a Ana escolhe o tema escuro no site da padaria, como o site vai lembrar disso na próxima página? Uma das respostas é o cookie: um pequeno texto que o servidor pede ao navegador para guardar e devolver em todos os pedidos seguintes. Nesta aula você cria, lê e apaga cookies, entende cada opção do setcookie e conhece o erro mais famoso dessa área: headers already sent.

A ideia: a comanda do restaurante

Num restaurante movimentado, o garçom não decora o que cada mesa pediu. Na primeira visita, ele deixa uma comanda na mesa com um número. Toda vez que você chama, ele olha a comanda e sabe quem você é.

O cookie é essa comanda: quem escreve é o servidor, quem guarda é o navegador, e o navegador a mostra, sozinho, em todo pedido seguinte para o mesmo site.

  NAVEGADOR                                         SERVIDOR (PHP)

 1. GET /tema.php  ─────────────────────────────▶  setcookie('tema', 'escuro')
                   ◀─────────────────────────────  Set-Cookie: tema=escuro; …
    guarda: tema=escuro                             (o PHP esquece tudo)

 2. GET /ler.php
    Cookie: tema=escuro ────────────────────────▶  $_COOKIE['tema'] → 'escuro'
                   ◀─────────────────────────────  página com o tema escuro

 3. (todo pedido seguinte ao mesmo site leva "Cookie: tema=escuro", até expirar)

Dois detalhes desse desenho explicam quase tudo o que vem a seguir:

• O cookie vai num cabeçalho, que viaja antes do conteúdo da página. Por isso existe o erro headers already sent.
• O cookie criado no passo 1 só volta no passo 2. No mesmo pedido em que você o cria, ele ainda não está em $_COOKIE.

Criar um cookie: setcookie

<?php
setcookie('tema', 'escuro', time() + 60 * 60 * 24 * 30);
echo "Cookie enviado.\n";
echo "O que chegou neste pedido: ";
var_dump($_COOKIE);

setcookie(

"Definir cookie": pede ao navegador para guardar um cookie.

'tema',

O nome do cookie (será a chave em $_COOKIE).

'escuro',

O valor. Sempre texto.

time() + 60 * 60 * 24 * 30

Até quando ele vale (a expiração). time() é o "agora", em segundos (veja Datas e Horas); somamos 60 segundos × 60 minutos × 24 horas × 30 dias. Sem esse argumento (ou com 0), é um cookie de sessão: some quando o navegador é fechado.

O -i do curl mostra os cabeçalhos da resposta. Olhe a linha Set-Cookie, e o $_COOKIE vazio:

$ curl -si localhost:8000/tema.php
HTTP/1.1 200 OK
Host: localhost:8000
Date: Sat, 17 Oct 2026 00:05:00 GMT
Connection: close
X-Powered-By: PHP/8.5.8
Set-Cookie: tema=escuro; expires=Mon, 16 Nov 2026 00:05:00 GMT; Max-Age=2592000
Content-type: text/html; charset=UTF-8

Cookie enviado.
O que chegou neste pedido: array(0) {
}

O PHP traduziu o time() + … em duas formas: expires (a data, no fuso de Greenwich, por isso 00:05 e não 21:05) e Max-Age=2592000 (os segundos que faltam: 30 dias). E o $_COOKIE está vazio, porque o navegador ainda nem recebeu o cookie.

O pedido seguinte

Para o curl se comportar como navegador e guardar os cookies, usamos um "pote de cookies": -c pote grava os cookies recebidos num arquivo, -b pote envia os cookies do arquivo.

$ curl -s -c pote localhost:8000/tema.php > /dev/null
$ cat pote
# Netscape HTTP Cookie File
# https://curl.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.

localhost	FALSE	/	FALSE	1794787500	tema	escuro
$ curl -s -b pote localhost:8000/tema.php
Cookie enviado.
O que chegou neste pedido: array(1) {
  ["tema"]=>
  string(6) "escuro"         « agora sim: veio no cabeçalho Cookie do pedido
}

O arquivo pote é parecido com o que o navegador guarda: o site (localhost), o caminho (/), a expiração (em segundos desde 1970), o nome e o valor.

Ler um cookie: $_COOKIE

$_COOKIE é uma superglobal como $_GET (veja Superglobais): um array com os cookies que o navegador mandou neste pedido. Leia sempre com um valor padrão, porque o cookie pode não existir (primeira visita, cookie expirado, pessoa que apagou os cookies):

<?php
$tema = $_COOKIE['tema'] ?? 'claro';
echo "Tema: $tema\n";

$ curl -s -b pote localhost:8000/ler.php
Tema: escuro

Exemplo: contador de visitas

<?php
$visitas = (int) ($_COOKIE['visitas'] ?? 0) + 1;
setcookie('visitas', (string) $visitas, time() + 60 * 60 * 24 * 365);
echo "Esta é a sua visita número $visitas.\n";

$ curl -s -b potev -c potev localhost:8000/visitas.php
Esta é a sua visita número 1.
$ curl -s -b potev -c potev localhost:8000/visitas.php
Esta é a sua visita número 2.
$ curl -s -b potev -c potev localhost:8000/visitas.php
Esta é a sua visita número 3.
$ curl -s -b "visitas=99" localhost:8000/visitas.php
Esta é a sua visita número 100.          « o visitante escolheu o valor do cookie

$_COOKIE['visitas'] ?? 0

O número que o navegador devolveu, ou 0 na primeira visita.

(int) ( … ) + 1

Converte para inteiro (o cookie é texto; um valor estranho como "abc" vira 0) e soma a visita atual.

setcookie('visitas', (string) $visitas, …)

Grava o número novo, que vai voltar no próximo pedido. O valor precisa ser texto, daí o (string).

A última linha mostra o aviso acima na prática: com -b "visitas=99", o "visitante" inventou o cookie. Para um contador de brincadeira, tudo bem. Para qualquer coisa que importe, não.

<?php
if (isset($_GET['esquecer'])) {
    setcookie('visitas', '', time() - 3600);
    echo "<p>Cookie apagado. Na próxima visita, a contagem recomeça.</p>";
} else {
    $visitas = (int) ($_COOKIE['visitas'] ?? 0) + 1;
    setcookie('visitas', (string) $visitas, time() + 60 * 60 * 24 * 365);
    echo "<p>Esta é a sua visita número $visitas.</p>";
}
?>
<form><button>Visitar de novo</button></form>
<form><button name="esquecer" value="1">Esquecer</button></form>
<p>$_COOKIE neste pedido:</p>
<pre><?php print_r($_COOKIE); ?></pre>

As opções: o array de opções

O setcookie aceita mais configurações além de nome, valor e expiração. A forma moderna (desde o PHP 7.3) é passar um array de opções no terceiro argumento:

<?php
setcookie('tema', 'escuro', [
    'expires'  => time() + 60 * 60 * 24 * 30,
    'path'     => '/',
    'secure'   => true,
    'httponly' => true,
    'samesite' => 'Lax',
]);
setcookie('aviso', 'Ana Souza');
echo "ok\n";

$ curl -si localhost:8000/opcoes.php
HTTP/1.1 200 OK
Host: localhost:8000
Date: Sat, 17 Oct 2026 00:05:00 GMT
Connection: close
X-Powered-By: PHP/8.5.8
Set-Cookie: tema=escuro; expires=Mon, 16 Nov 2026 00:05:00 GMT; Max-Age=2592000; path=/; secure; HttpOnly; SameSite=Lax
Set-Cookie: aviso=Ana%20Souza
Content-type: text/html; charset=UTF-8

ok

Cada opção virou um pedaço do cabeçalho Set-Cookie. Repare também no segundo cookie: o espaço de Ana Souza viajou como %20. O setcookie codifica o valor sozinho, e o PHP decodifica ao montar $_COOKIE.

A forma antiga, com tudo em argumentos separados, ainda funciona e aparece muito em códigos mais velhos:

// setcookie(nome, valor, expires, path, domain, secure, httponly)
setcookie('tema', 'escuro', time() + 3600, '/', '', true, true);

Ela não tem lugar para o samesite, e é fácil errar a ordem. Prefira o array.

Apagar um cookie

Não existe "apagar" no protocolo: o servidor pede para o navegador substituir o cookie por um já vencido. O jeito clássico é uma data no passado:

<?php
setcookie('tema', '', time() - 3600);
echo "Cookie apagado.\n";

$ curl -si -b pote -c pote localhost:8000/apagar.php
HTTP/1.1 200 OK
…
Set-Cookie: tema=deleted; expires=Thu, 01 Jan 1970 00:00:01 GMT; Max-Age=0
Content-type: text/html; charset=UTF-8

Cookie apagado.
$ curl -s -b pote localhost:8000/ler.php
Tema: claro          « o cookie sumiu do pote, e voltou o valor padrão

O PHP, ao ver um valor vazio, mandou tema=deleted com vencimento em 1970 e Max-Age=0: o navegador descarta na hora. Dois cuidados:

• Use o mesmo path e domain com que o cookie foi criado. Para o navegador, tema com path=/ e tema com path=/loja são cookies diferentes.
• O $_COOKIE['tema'] do pedido atual continua lá (ele veio no pedido). Se o resto da página usa o valor, faça também unset($_COOKIE['tema']).

"Headers already sent": o erro mais famoso

A Ana escreveu uma saudação antes de criar o cookie:

<?php
echo "Bem-vinda!\n";
setcookie('tema', 'escuro');

$ curl -si localhost:8000/erro.php
HTTP/1.1 200 OK
Host: localhost:8000
Date: Sat, 17 Oct 2026 00:05:00 GMT
Connection: close
X-Powered-By: PHP/8.5.8
Content-type: text/html; charset=UTF-8

Bem-vinda!
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /home/ana/site/c/erro.php:2) in <b>/home/ana/site/c/erro.php</b> on line <b>3</b><br />

Não há Set-Cookie nos cabeçalhos: o cookie não foi criado. Lembre do desenho: uma resposta HTTP é cabeçalhos primeiro, conteúdo depois, como uma carta em que o envelope é fechado antes de o carteiro sair. No momento em que o echo da linha 2 escreveu a primeira letra do conteúdo, o PHP precisou mandar os cabeçalhos (o envelope) pela rede. Quando a linha 3 tentou acrescentar um Set-Cookie, o envelope já tinha saído.

A saída invisível

O caso mais traiçoeiro é quando você não vê nenhum echo. Este arquivo tem só uma linha em branco antes do <?php (a linha 1 está vazia; o <?php está na linha 2):

<?php
setcookie("tema", "escuro");
echo "ok\n";

$ curl -si localhost:8000/erro2.php
…
Content-type: text/html; charset=UTF-8


<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /home/ana/site/c/erro2.php:1) in <b>/home/ana/site/c/erro2.php</b> on line <b>3</b><br />
ok

Tudo o que está fora de <?php … ?> é saída, inclusive uma linha vazia ou um espaço. O "output started at …:1" aponta a linha 1: a linha em branco. Outros culpados comuns:

• Um arquivo incluído (include e require) que termina com ?> seguido de uma linha em branco. Por isso a recomendação: em arquivos só de PHP, não feche o ?> no final.
• O BOM: três bytes invisíveis que alguns editores (o Bloco de Notas antigo do Windows) colocam no começo de arquivos UTF-8. Salve como "UTF-8 sem BOM".
• Um Warning ou Notice anterior: a própria mensagem de aviso é saída.

Alguns servidores ligam a configuração output_buffering no php.ini: o PHP guarda a saída num "buffer" (área de espera) antes de mandar, e o erro só aparece depois de alguns kilobytes de saída. É por isso que um código com esse problema às vezes "funciona no servidor e não no meu computador" (ou o contrário). Não conte com isso: siga a regra.

Limites e privacidade

O que guardar: preferências pequenas e sem segredo (tema, idioma, "já viu o aviso"), e o identificador da sessão (que o PHP cria sozinho, em Sessões).

O que nunca guardar: senhas, números de cartão, CPF, nada que dê acesso ("logado=sim", "admin=1"), nada que você não queira que a pessoa leia ou mude.

Privacidade: cookies também servem para seguir pessoas. Os "cookies de terceiros" (de anúncios e rastreadores embutidos em vários sites) contam a uma empresa por onde você passou. Por isso leis como a LGPD (no Brasil) e a GDPR (na Europa) exigem que o site informe que cookies usa e peça consentimento para os que não são essenciais, e os navegadores vêm bloqueando cookies de terceiros. Cookies essenciais para o site funcionar (sessão de login, carrinho) não precisam de consentimento, mas precisam ser informados na política de privacidade.

Quando dá errado

<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /home/ana/site/c/erro.php:2) in <b>/home/ana/site/c/erro.php</b> on line <b>3</b><br />

O que chegou neste pedido: array(0) {
}

Referência

Exercícios

<?php
setcookie('tema', $_GET['tema'] ?? 'claro');
$tema = $_COOKIE['tema'] ?? 'claro';
?>
<p>Tema: <?= htmlspecialchars($tema) ?></p>
<p><a href="?tema=claro">Claro</a> | <a href="?tema=escuro">Escuro</a> | <a href="?">Recarregar</a></p>

<?php
if (isset($_GET['tema'])) {
    setcookie('tema', $_GET['tema'], time() + 60 * 60 * 24 * 30);
}
$tema = $_GET['tema'] ?? $_COOKIE['tema'] ?? 'claro';
?>
<p>Tema: <?= htmlspecialchars($tema) ?></p>
<p><a href="?tema=claro">Claro</a> | <a href="?tema=escuro">Escuro</a> | <a href="?">Recarregar</a></p>

<?php
setcookie('idioma', 'pt-BR', time() + 60 * 60 * 24 * 365);
echo "<p>Idioma salvo.</p>";

<?php
setcookie('idioma', 'pt-BR', [
    'expires'  => time() + 60 * 60 * 24 * 365,
    'path'     => '/',
    'httponly' => true,
    'samesite' => 'Lax',
]);
echo "<p>Idioma salvo.</p>";

Resumo

• Cookie = texto que o servidor pede ao navegador para guardar (Set-Cookie) e que volta em todo pedido seguinte (Cookie).
• setcookie(nome, valor, opções); a expiração é time() + segundos; sem ela, o cookie some ao fechar o navegador.
• Leia com $_COOKIE['nome'] ?? padrão. O cookie criado agora só aparece no próximo pedido.
• Opções: path ('/'), domain, secure (só HTTPS), httponly (longe do JavaScript), samesite ('Lax'). Use o array de opções.
• Apagar = gravar vencido (time() - 3600), com o mesmo path/domain.
• setcookie vem antes de qualquer saída; senão, headers already sent. A pista é o "output started at".
• Cookie é dado do visitante: pequeno (até ~4 KB), sem segredos, validado e escapado. Para login, use Sessões.