setcookie
(PHP 4, PHP 5, PHP 7, PHP 8)
setcookie — Envia um cookie
Descrição
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.
Parâmetros
A » RFC 6265 fornece a referência
normativa de como cada parâmetro de setcookie()
é interpretado.
name
-
O 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_options
recebe
uma timestamp Unix, ao contrário do formato de data Wdy,
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().
Valor Retornado
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.
Exemplos
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:
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.
Notas
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_buffering
no
php.ini ou em arquivos de configuração do servidor.
Problemas comuns:
-
Os cookies não estarão disponíveis até o próximo carregamento da página
para a qual o cookie deverá estar visível. Para testar se um cookie foi
enviado com sucesso, deve ser verificado o cookie no próximo carregamento da
página antes que ele expire. O tempo para expirar é configurado pelo
parâmetro
expires_or_options
. Uma boa maneira de depurar a
existência dos cookies é chamando a função print_r($_COOKIE);
.
-
Os cookies devem ser excluídos com os mesmos parâmetros com os quais
foram configurados. Se o argumento
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.
-
Quando um cookie for configurado com o valor
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
.
-
Nomes de cookies podem ser configurados como arrays e estarão disponíves
para os scripts PHP como arrays, mas cookies separados serão armazenados
no sistema do usuário. Deve ser considerado utilizar explode()
para enviar um cookie com nomes e valores múltiplos. Não é recomendado o
uso da função serialize() para esse propósito, pois
pode resultar em furos de segurança.
Várias chamadas para a função setcookie() são feitas na ordem em que são chamadas.