setcookie

(PHP 3, PHP 4 , PHP 5)

setcookie -- Envia um cookie

Descrição

bool setcookie ( string name [, string value [, int expire [, string path [, string domain [, int secure]]]]] )

setcookie() define um cookie para ser enviado junto com o resto dos cabeçalhos HTTP. Como outros cabeçalhos, cookies devem ser enviados antes de qualquer saída do seu script (esta é uma restrição do protocolo). Isto requer que você utilize esta função antes de qualquer saída, incluindo as tags <html> e <head> assim como quaiquer espaços em branco. Se já tiver sido enviada qualquer saída antes dessa função, setcookie() irá falhar e retornar FALSE. Se setcookie() for bem sucedida, irá retornar TRUE. Isto não indica que o usuário aceitou o cookie.

Nota: A partir do PHP 4, você pode usar o buffer de saída para enviar saída antes de utilizar esta função, o que fará com que toda a saída para o browser seja guardada em buffer no servidor até que você envie ela. Você poderá fazer isso utilizando as funções ob_start() e ob_end_flush() no seu script, ou definindo a diretiva de configuração output_buffering no seu php.ini ou nos arquivos de configuração do servidor.

Todos os argumentos com excessão de name são opcionais. Você pode também substituir um argumento com uma string vazia ("") para pular este argumento. Devido a expire e secure serem inteiros, eles não podem ser pulados com uma string vazia, use um zero (0). A seguinte tabela explica cada parâmetro da função setcookie(), Tenha certeza de ler Netscape cookie specification para detalhes de como funciona cada parâmetro de setcookie() e RFC 2965 para informações adicionais de como cookies HTTP fucionam.

Tabela 1. Os parâmetros de setcookie() explicados

ParâmetroDescriçãoExemplos
name O nome do cookie. 'cookiename' é chamado como $_COOKIE['cookiename']
value O valor do cookie. Este valor é guardado no computador do cliente, não guarde informações sensíveis. Assumindo que name e 'cookiename', este valor é obtido atraves de $_COOKIE['cookiename']
expire O tempo para o cookie expirar. Este é um timestamp Unix assim é o número de segundos desde epoch. Em outras palavras, normalmente você vai definir com a função time() mais o número de segundos que você queira té que expire. Ou você pode usar a função mktime(). time()+60*60*24*30 irá fazer com que o cookie expire em 30 dias. Se não for definido, o cookie irá expirar ao fim da sessão (quando o browser fechar).
path O caminho no servidor para qual o cookie estará disponível. Se for definido '/', o cookie estará disponível para todo o domain(domínio). Se for definido '/foo/', o cookie estará disponível apenas no diretório /foo/ e todos os sub-diretórios /foo/bar/ de domain. O valor padrão é o diretório que o cookie esta sendo definido.
domain O domínio que o cookie estará disponível. Para fazer o cookie estar disponível para todos os subdomínios de example.com então você deve definir como '.example.com'. O . não é requerido, mas torna compativel com mais browsers. Definindo como www.example.com fará o cookie estar disponível apenas para o subdomínio www. Você pode ler spec para maiores detalhes.
secure Indica que o cookie deve ser transmitido sobre uma conexão segura HTTPS. Quando for definido como 1, o cookie só será definido se existir uma conexão segura. O padrão é 0. 0 ou 1

Depois que os cookies foram definidos, eles podem ser acessados na próxima página com as matrizes $_COOKIE ou $HTTP_COOKIE_VARS. Note que, autoglobals como $_COOKIE estão disponíveis a apartir do PHP 4.1.0. $HTTP_COOKIE_VARS existe desde o PHP 3. Os valores dos cookies também existem em $_REQUEST.

Nota: Se a diretiva do PHP register_globals estiver definida como on então os valores dos cookie também estarão em variáveis. Nos nossos exemplos abaixo, $TextCookie irá existir. É recomendado usar $_COOKIE.

Problemas comuns:

No PHP 3, multiplas chamadas a setcookie() no mesmo script serão feitas em ordem reversa. Se você esta tentando excluir um cookie antes de inserir outro, você deve colocar a inserção antes da exclusão. A partir do PHP 4, multiplas chamadas a setcookie() são feitas na ordem de chamada.

Alguns exemplos de como enviar cookies:

Exemplo 1. setcookie() enviando cookies

<?php
$value
= 'something from somewhere';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600); /* expira em uma hora */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", ".example.com", 1);
?>

Note que o valor do cookie será automaticamente codificado como url quando você envia o cookie, e quando é recebido, é automaticamente decodificado e definido para uma variável com o mesmo nome do cookie. Se você não quiser isto, você pode ao invés usar setrawcookie() se você estiver usando o PHP 5. Para ver o conteúdo do nosso cookie de teste em um script, simplesmente use um dos seguintes exemplos:

<?php
// Mostra um cookie
echo $_COOKIE["TestCookie"];
echo
$HTTP_COOKIE_VARS["TestCookie"];

// Mostr todos os cookies
print_r($_COOKIE);
?>

Quando estiver excluindo um cookie, você deve se assegurar que a data de expiração esta no passado, para ativar o mecanismo de remoção do seu browser. Exemplos a seguir de como excluir cookies enviados nos exemplos anteriores:

Exemplo 2. Exemplo setcookie() de exclusão

<?php
// define a data de expiração do cookie para uma hora atrás
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".example.com", 1);
?>

Você pode também criar uma matriz de cookies usando a marcação de matriz no nome do cookie. Isto tem o efeito de definir tantos cookies quantos os elementos da matriz, mas quando o cookie é recebido pelo seu script, todos os cookies são colocados em uma matriz com o nome do cookie:

Exemplo 3. setcookie() e matrizes

<?php
// define os cookies
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// após a pagina recarregar, mostra eles
if (isset($_COOKIE['cookie'])) {
    foreach (
$_COOKIE['cookie'] as $name => $value) {
        echo
"$name : $value <br />\n";
    }
}
?>

O qual mostra:

three : cookiethree
two : cookietwo
one : cookieone

Nota: Para maiores informações sobre cookie, veja a espeficação de cookies da Netscape em http://wp.netscape.com/newsref/std/cookie_spec.html e RFC 2965.

Você deve saber que expire leva um Unix timestamp, em oposição a uma data formatada Wdy, DD-Mon-YYYY HH:MM:SS GMT, isto é porque o PHP faz esta conversão internamente.

expire é comparado com o horário do cliente o qual pode ser diferente do horário do servidor.

Nota: Microsoft Internet Explorer 4 com Service Pack 1 não lida corretamente com cookies que tenham o parâmetro path definido.

Netscape Communicator 4.05 e Microsoft Internet Explorer 3.x parecem não manusear corretamente cookies quando o path e time não estão definidos.

Veja também header(), setrawcookie() e a sessão sobre cookies.