Manual do PHP
Anterior |  | Próxima

# setcookie

(PHP 3, PHP 4 )

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: No 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âmetro | Descrição | Exemplos
--- | --- | ---
`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:

- Cookies não estarão visiveis até a próxima vez que a pagina para a qual devem estar visiveis seja carregada novamente. Para testar se um cookie foi realmente definido, confira o cookie na próxima vez que a pagina seja carregada e antes que expire. O tempo de expirar é definido pelo parâmetro `expire`. Uma maneira fácil de fazer o debug da existencia de cookies é simplesmente usar `print_r($_COOKIE);`.

- Cookies devem ser excluídos com os mesmos parâmetros que foram criados. Se o argumento valor for uma string vazia (""), e todos os outros argumentos forem iguais, então o cookie com o nome especificado será excluído do cliente.

- Nomes de cookies podem ser definidos como uma matriz de nomes e estará disponível nos scripts PHP como uma matriz, mas são guardados como cookies separados no sistema do usuário. Considere utilizar explode() ou serialize() para definir um cookie com multiplos nomes e valores.

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. No 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. Para ver o conteúdo do nosso cookie de teste, 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://www.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.

> 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() e a sessão sobre cookies.

Anterior | Principal | Próxima
headers_sent | Acima | setrawcookie