(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, os cookies devem ser enviados
antes de qualquer saída do script (isso é
uma restrição do protocolo). Isso significa que as chamadas a essa função devem ser colocadas antes de qualquer
saída, incluindo as tags <html> e
<head>, assim como espaços em branco.
Uma vez que os cookies foram definidos, 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 array $_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 é armazenado no computador do cliente; não
deve ser armazenada 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 é um timestamp Unix,
portanto é o número de segundos desde a época Unix.
Uma maneira de configurar esse valor é adicionando o número de segundos em 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 (quando o navegador fechar).
Nota:
O parâmetro
expires_or_optionsrecebe uma timestamp Unix, ao contrário do formato de dataWdy, DD-Mon-YYYY HH:MM:SS GMT, isso acontece 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), basta definir o valor
para o nome do domínio ('example.com', nesse caso).
Navegadores 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 navegadores), mas essa informação
é constantemente discutida. Foi adicionada no PHP 5.2.0.
true ou false
options
Um array associativo que pode ter qualquer uma das 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 para os
parâmetros de mesmo nome. O valor do elemento samesite
deve ser None, Lax
ou Strict.
Se uma das opções não for informada, os valores padrão serã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 houver 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 data do cookie agora é '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); /* expira em 1 hora */
setcookie("CookieTeste", $value, time()+3600, "/~rasmus/", "example.com", true);
?>Note que a porção do valor do cookie será automaticamente codificada em URL quando o cookie for enviado, e quando ele for recebido, será automaticamente decodificado e atribuído a uma variável com o mesmo nome do cookie. Se esta não for a intenção, pode ser utilizada em seu lugar a função setrawcookie(). Para ver o conteúdo do cookie de teste em um script, simplesmente utilize um dos exemplos abaixo:
<?php
// Mostra um cookie individual
echo $_COOKIE["CookieTeste"];
// Outra maneira de depurar/testar é vendo todos os cookies
print_r($_COOKIE);
?>
Exemplo #2 Exemplo de setcookie() para apagar cookies
Quando um cookie estiver sendo excluído, deve-se garantir que a data de expiração dele está no passado, para acionar o mecanismo de remoção no navegador. O exemplo a seguir mostra como excluir 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
Cookies de array também podem ser enviados, utilizando a notação de array no nome dele. Isso tem o efeito de enviar tantos cookies quantos elementos houver no array, mas quando o cookie for recebido pelo script, os valores serão todos 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");
// Mostra os cookies depois que a página recarregar
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 a RFC 6265, seção 4, mas deve ser suportado por navegadores conforme a RFC 6265, seção 5.
Nota:
Você pode utilizar o buffer de saída para enviar a saída antes de chamar essa função, com o custo de toda a saída para o navegador ser armazenada em buffer no servidor até que seja enviada. Isso pode ser feito chamando ob_start() e ob_end_flush() no script, ou configurando a diretiva
output_bufferingno php.ini ou em arquivos de configuração do servidor.
Problemas comuns:
expires_or_options. Uma boa maneira de depurar a
existência dos cookies é chamando a função print_r($_COOKIE);.
value for uma string vazia,
e todos os outros argumentos forem iguais à chamada anterior de setcookie(),
o cookie com o nome especificado será excluído do cliente remoto.
Internamente, isso é feito colocando o valor do cookie para 'deleted' e a
data de expiração para um ano no passado.
false, será realizada uma tentativa de
excluir o cookie. Portanto, evite utilizar valores booleanos. No lugar deles,
utilize 0 para false e 1 para true.
Várias chamadas para a função setcookie() são feitas na ordem em que são chamadas.