(PHP 4, PHP 5)
setcookie — Envia um cookie
$name
[, string $value
[, int $expire = 0
[, string $path
[, string $domain
[, bool $secure = false
[, bool $httponly = false
]]]]]] )A função setcookie() define um cookie para ser enviado juntamente com o resto dos 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> e também espaços em branco.
Uma vez que o cookie foi setado, ele pode ser acessado na próxima página através dos arrays $_COOKIE e $HTTP_COOKIE_VARS. Note que as superglobais como $_COOKIE estão disponíveis a partir do PHP 4.1.0. Os valores dos cookies também existem na variável $_REQUEST.
Todos os argumentos, exceto o name, são opcionais.
Você pode também colocar como argumento uma string vazia
("") para pular o argumento. Como o
argumento expire é um inteiro, ele não pode ser
escapado com uma string vazia, por isso utilize um zero
(0) no lugar.
Veja a » RFC 6265 para ver como cada parâmetro de setcookie() funciona.
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
'nomedocookie', o valor pode ser lido través de
$_COOKIE['nomedocookie']
expireO tempo para o cookie expirar. Esse valor é uma timestamp Unix, portanto é o número de segundos desde a época (epoch). Em outras palavras, você provavelmente irá utilizar isso com a função time() mais o número de segundos que você quer que ele expire. Ou você pode utilizar a função mktime(). time()+60*60*24*30 irá configurar o cookie para expirar em 30 dias. Se configurado para 0, ou omitido, o cookie irá expirar ao fim da sessao (quando o navegador fechar).
Nota:
Você pode ver que o parâmetro
expirerecebe uma timestamp Unix, ao contrário do formato de data Wdy, DD-Mon-YYYY HH:MM:SS GMT, isso se dá porque o PHP faz essa conversão internamente.
path
O caminho no servidor aonde o cookie estará disponível. Se configurado
para '/', o cookie estará dosponí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.
domainO domínio para qual o cookie estará disponível. Configurando o domínio para 'www.example.com' fará com que o cookie esteja disponível no subdomínio www e nos subdomínios superiores. Cookies disponíveis para um domínio inferior, como 'example.com' estarão disponíveis para subdomínios superiores, como 'www.example.com'. 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ó podera ser transimitido 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
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.
Alguns exemplos para seguir de como 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", 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 atribuido 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"];
echo $HTTP_COOKIE_VARS["CookieTeste"];
// Outra maneira de depurar(debug)/testar é vendo todos os cookies
print_r($_COOKIE);
?>
Exemplo #2 Exemplo de setcookie() para deletar cookies
Quando estiver deletando um cookie, tenha certeza de que a data de expiração dele está no passado, para acionar o mecanismo de remoção do seu 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) {
echo "$nome : $valor <br />\n";
}
}
?>
O exemplo acima irá imprimir:
tres : cookietres dois : cookiedois um : cookieum
| Versão | Descrição |
|---|---|
| 5.2.0 |
O parâmetro httponly foi adicionado.
|
Nota:
Você pode utilizar o output buffering para enviar saída antes de chamar essa função, com o custo de toda sua saída ser guardada em buffer até que você a envie. Você pode fazer isso chamando ob_start() e ob_end_flush() em seu script, ou configurando a diretiva output_buffering no seu php.ini ou arquivos de configuração do servidor.
Nota:
Se a diretiva register_globals estiver configurada como on então os valores dos cookies serão colocadas em variáveis. Em nossos exemplos acima, a variável $CookieTeste irá existir. É recomendado o uso de $_COOKIE.
Problemas comuns:
expira. Uma maneira boa de depurar a
existência dos cookies é chamando a função
print_r($_COOKIE);.
FALSE, e todos os outros argumentos forem iguais a chamada anterior de
setcookie, então o cookie com o nome especificado será deletado 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á 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.