(PHP 4, PHP 5, PHP 7, PHP 8)
setcookie — Envia um cookie
$name,$value = "",$expires_or_options = 0,$path = "",$domain = "",$secure = false,$httponly = falseAssinatura alternativa disponível a partir do PHP 7.3.0 (sem suporte a parâmetros nomeados):
A função setcookie() define um cookie para ser enviado juntamente com os cabeçalhos HTTP. Como outros cabeçalhos (headers), os cookies devem ser enviados antes de qualquer saída do seu script (isso é uma restrição do protocolo). O que quer dizer que você deve colocar chamadas a essa função antes de qualquer saída, incluindo as tags <html> e <head> assim como espaços em branco.
Uma vez que os cookies foram setados, eles podem ser acessados no próximo carregamento da página através do array $_COOKIE. Os valores dos cookies também podem existir no $_REQUEST.
A » RFC 6265 fornece a referência normativa de como cada parâmetro de setcookie() é interpretado.
nameO nome do cookie.
value O valor do cookie. Esse valor é guardado no computador do cliente; não guarde informação sensível. Supondo que o name seja 'cookiename', o valor pode ser lido através de $_COOKIE['cookiename']
expires_or_options O tempo para o cookie expirar. Esse valor é uma timestamp Unix, portanto é o número de segundos desde a época (epoch). Um jeito de configurar esse valor é por adicionando o número de segundos que o cookie deve durar antes de expirar ao resultado da função time(). Por exemplo, time()+60*60*24*30 irá configurar o cookie para expirar em 30 dias. Outra opção é usar a função mktime(). Se configurado para 0 ou omitido, o cookie vai expirar no final da sessão (ao navegador fechar).
Nota:
Você pode ver que o parâmetro
expires_or_optionsrecebe uma timestamp Unix, ao contrário do formato de dataWdy, DD-Mon-YYYY HH:MM:SS GMT, isso se dá porque o PHP faz essa conversão internamente.
path O caminho no servidor onde o cookie estará disponível. Se configurado para '/', o cookie estará disponível para todo o domain. Se configurado para o diretório '/foo/', o cookie estará disponível apenas dentro do diretório /foo/ e todos os subdiretórios como /foo/bar/ do domain. O valor padrão é o diretório atual onde o cookie está sendo configurado.
domain O (sub)domínio para qual o cookie estará disponível. Definindo para um subdomínio (como 'www.example.com') deixará o cookie disponível para aquele subdomínio e todos os outros sub-domínios abaixo dele (exemplo w2.www.example.com). Para deixar o cookie disponível para todo o domínio (incluindo todos os subdomínios dele), simplesmente defina o valor para o nome do domínio ('example.com', nesse caso).
Browsers antigos ainda implementam a » RFC 2109 e podem requerer um . no início para funcionar com todos os subdomínios.
secure Indica que o cookie só poderá ser transmitido sob uma conexão segura HTTPS do cliente. Quando configurado para true, o cookie será enviado somente se uma conexão segura existir. No lado do servidor, fica por conta do programador enviar esse tipo de cookie somente sob uma conexão segura (ex respeitando $_SERVER["HTTPS"]).
httponly Quando for true o cookie será acessível somente sob o protocolo HTTP. Isso significa que o cookie não será acessível por linguagens de script, como JavaScript. É dito que essa configuração pode ajudar a reduzir ou identificar roubos de identidade através de ataques do tipo XSS (entretanto ela não é suportada por todos os browsers), mas essa informação é constantemente discutida. Foi adicionada no PHP 5.2.0. true ou false
options Um array associativo onde quaisquer chaves expires, path, domain, secure, httponly e samesite. Se qualquer outra chave estiver presente, um alerta E_WARNING é gerado. Os valores têm o mesmo efeito como descrito acima, para os parâmetros de mesmo nome. O valor de samesite deve ser None, Lax ou Strict. Se uma das opções não é informada, os valores padrão são os mesmos valores padrão dos parâmetros explícitos. Se samesite for omitido, o atributo SameSite do cookie não será atribuído.
Nota:
Para definir um cookie que inclui atributos que não estão entre as chaves listadas, use a função header().
Se existe saída antes da chamada dessa função, setcookie() irá falhar e retornará false. Se a função setcookie() for executada com sucesso, ela retornará true. Isso não indica que o usuário aceitou o cookie.
| Versão | Descrição |
|---|---|
| 8.2.0 | O formato de timestamp do cookie foi alterado para 'D, d M Y H:i:s \G\M\T'; anteriormente era 'D, d-M-Y H:i:s T'. |
| 7.3.0 | Uma assinatura alternativa para suportar o array options foi adicionado. Essa assinatura também permite configurar o atributo SameSite do cookie. |
Os exemplos a seguir demonstram algumas formas de enviar cookies.
Exemplo #1 Exemplo de setcookie() para enviar cookies
<?php
$value = 'alguma coisa de algum lugar';
setcookie("CookieTeste", $value);
setcookie("CookieTeste", $value, time()+3600);
setcookie("CookieTeste", $value, time()+3600, "/~rasmus/", ".example.com", 1);
?>Note que a porção do valor do cookie será automaticamente codificada com urlencode quando você enviar o cookie, e quando ele for recebido, será automaticamente decodificado e atribuído a uma variável com o mesmo nome do cookie. Se você não quer que isso aconteça, você pode utilizar no lugar a função setrawcookie() se você estiver utilizando o PHP 5. Para ver o conteúdo do nosso cookie de teste em um script, simplesmente utilize um dos exemplos abaixo:
<?php
// Mostra um cookie individual
echo $_COOKIE["CookieTeste"];
// Outra maneira de depurar(debug)/testar é vendo todos os cookies
print_r($_COOKIE);
?>Exemplo #2 Exemplo de setcookie() para apagar cookies
Quando estiver apagando um cookie, tenha certeza de que a data de expiração dele está no passado, para acionar o mecanismo de remoção do navegador. O exemplo a seguir mostra como deletar os cookies enviados no exemplo anterior:
<?php
// Configura a data de expiração para uma hora atrás
setcookie("CookieTeste", "", time() - 3600);
setcookie("CookieTeste", "", time() - 3600, "/~rasmus/", ".example.com", 1);
?>Exemplo #3 setcookie() e arrays
Você pode também enviar cookies de array, utilizando a notação de array no nome dele. Isso tem o efeito de enviar tantos cookies quantos elementos houverem no array, mas quando o cookie for recebido todos os valores serão colocados em um array com o nome do cookie:
<?php
// envia os cookies
setcookie("cookie[tres]", "cookietres");
setcookie("cookie[dois]", "cookiedois);
setcookie("cookie[um]", "cookieum");
// Depois que a página recarregar, mostra eles
if (isset($_COOKIE['cookie'])) {
foreach ($_COOKIE['cookie'] as $nome => $valor) {
$nome = htmlspecialchars($nome);
$valor = htmlspecialchars($valor);
echo "$nome : $valor <br />\n";
}
}
?>O exemplo acima produzirá:
tres : cookietres dois : cookiedois um : cookieum
Nota: Utilizar caracteres como
[e]no nome do cookie não é válido conforme o RFC 6265, seção 4, mas deve ser suportado por navegadores conforme o RFC 6265, seção 5.
Nota:
Você pode utilizar o output buffering para enviar a saída antes de chamar essa função, com o custo de toda sua saída ser guardada em buffer no servidor até que você a envie. Você pode fazer isso chamando ob_start() e ob_end_flush() em seu script, ou configurando a diretiva
output_bufferingno seu php.ini ou arquivos de configuração do servidor.
Problemas comuns:
expires_or_options. Uma maneira boa de depurar a existência dos cookies é chamando a função print_r($_COOKIE);. 'deleted' e a data de expiração para um ano no passado. false será tentando deletar o cookie. Portanto evite utilizar valores booleanos. No lugar, utilize 0 para false e 1 for true. Várias chamadas para a função setcookie() são feitas na ordem em que são chamadas.