Funções da Network
PHP Manual

setcookie

(PHP 4, PHP 5)

setcookieEnvia um cookie

Descrição

bool setcookie ( string $nome [, string $valor [, int $expira [, string $caminho [, string $domínio [, bool $seguro [, bool $somente http ]]]]]] )

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 através dos arrays $_COOKIE e $HTTP_COOKIE_VARS. Note que as superglobais como $_COOKIE ou $HTTP_COOKIE_VARS estão disponíveis a partir do PHP 4.1.0. Os valores dos cookies também existem na variável $_REQUEST.

Parâmetros

Todos os argumentos, excento o name, são opcionais. Você pode também colocar como argumento uma string vazia ("") para pular o argumento. Por que 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 » especificação de cookie do Netscape para ver como cada parâmetro de setcookie() funciona.

nome

O nome do cookie.

valor

O valor do cookie. Esse valor é guardado no computador do cliente; não guarde informação sensível. Supondo que o nome é 'nomedocookie', o valor pode ser lido través de $_COOKIE['nomedocookie']

expira

O 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 daqui a 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 expira recebe 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.
expira é comparado com a hora do computador do cliente, que pode ser diferente da hora do servidor.

caminho

O caminho no servidor aonde o cookie estará disponível. Se configurado para '/', o cookie estará dosponível para todo o domínio. 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 domínio. O valor padrão é o diretório atual aonde o cookie está sendo configurado.

domínio

O domínio para qual o domínio estará disponível. Para fazer com que ele esteja disponível para todos os subdomínios de example.com então você deve configurar ele para '.example.com'. O . não é obrigatório mas faz com que seja compatível com mais navegadores. Configurando ele para www.example.com ele fará com que o cookie esteja disponível somente para o subdomínio www. Veja a especificação de 'tail matching' em » spec para maiores detalhes.

seguro

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. O padrão é FALSE. No lado do servidor, fica por conta do programador enviar esse tipo de cookie somente sob uma conexão segura (ex respeitando $_SERVER["HTTPS"]).

somente http

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. Essa configuração pode efetivamente ajudar a reduzir ou identificar roubos através de ataques do tipo XSS (entretanto ela não é suportada por todos os browsers). Foi adicionada no PHP 5.2.0. TRUE ou FALSE

Valor Retornado

Se existe saída antes da chamada dessa função, setcookie() irá falhar e retornará FALSE. Se a função setcookie() executar com sucesso, ela retornará TRUE. Isso não quer dizer que o usuário aceitou o cookie.

Exemplos

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"$valuetime()+3600);  /* expire in 1 hour */
setcookie("CookieTeste"$valuetime()+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 exemplos

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 A função 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

Histórico

Versão Descrição
5.2.0 O parâmetro httponly foi adicionado.

Notas

Nota: A partir do PHP 4, você pode utilizar o output buffering para enviar saída antes de chamar essa função, com o custo (overhead) 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:

Várias chamadas para a função setcookie() são feitas na ordem em que são chamadas.

Veja Também


Funções da Network
PHP Manual