Olá pessoal!
Agora estarei publicando as traduções, links e etc sobre a linguagem Perl.
E a princípio, neste post você poderá conferir a tradução da documentação sobre o módulo CGI::Cookie.
Se você não sabe como se pronúncia "Perl":
http://www.ipct.pucrs.br/flavio/perl/brasil/perl.wav
Para maiores informações sobre o módulo CGI:
http://perldoc.perl.org/CGI.html
CGI::Cookie
Fonte original (inglês): http://perldoc.perl.org/CGI/Cookie.html
Descrição
CGI::Cookie é uma interface para cookies Netscape (HTTP/1.1), uma inovação que permite que os usuários armazenem
informação persistente no browser da conexão. Embora CGI::Cookie é pretendido ser usado conjuntamente com CGI.pm
(e de fato usado por ele internamente), você pode usar este módulo independentemente.
Para maiores informações sobre cookies:
http://www.ics.uci.edu/pub/ietf/http/rfc2109.txt
Usando CGI::Cookie
CGI::Cookie é orientado à objetos. Cada objeto do cookie tem um name e value.
O name é um valor escalar. O value é um valor escalar ou lista (listas associativas são também permitidas).
Cookies também possuem vários atributos opcionais, incluindo:
- Expiration date
A data de expiração diz ao browser quanto tempo irá durar o cookie. Se o cookie tiver especificado uma data de expiração no futuro, o browser irá armazenar informação do cookie no usuário e retornará ao usuário cada vez que o usuário reconectar (até que a data de expiração seja alcançado). Se o cookie tiver especificado uma data de expiração no passado, o browser irá remover o cookie do usuário. Se a data de expiração não for especificada, o cookie existirá até que o usuário feche o browser.
- Domain
Esse é parcial ou completo para cada cookie válido. O browser irá retornar o cookie para algum host que combine com o nome do domínio. Por exemplo, se você especificar um domínio como ".capricorn.com", então será retornado o cookie que corresponda com "www.capricorn.com", "ftp.capricorn.com", "feckless.capricorn.com", etc. Os nomes do domínio devem conter pelo menos dois períodos para impedir tentativas de combinar em domínios do nível superior como ".edu". Se nenhum domínio é especificado, então o browser irá sempre retornar o cookie para o servidor no host que o originou.
- Path
Se você especificar este atributo, o browser irá checar a url do seu script antes de retornar o cookie. Por exemplo, se você especificar o path "/cgi-bin/", então o cookie irá ser retornado para cada script "/cgi-bin/tally.pl", "/cgi-bin/order.pl", e "/cgi-bin/customer_service/complain.pl", mas não para o script "/cgi-private/site_admin.pl". Por padrão, o path é setado para "/", então todos scripts do seu site irão receber o cookie.
- Secure flag
Se o atributo é especificado, o cookie somente será enviado para seu script se a requisição CGI está ocorrendo com segurança, como SSL.
Criando novos cookies
my $c = new CGI::Cookie(-name => 'foo',
-value => 'bar',
-expires => '+3M',
-domain => '.capricorn.com',
-path => '/cgi-bin/database',
-secure => 1
);
Criar cookies com o novo método. O -name e -value são parâmetros requeridos. O name é um valor escalar. O value pode ser um escalar, uma lista, ou um hash. (No futuro cookies suportarão objetos serializados)
-expires aceita alguns relativos e absolutos formatos de data do CGI.pm, por exemplo "+3M" para 3 meses.
-domain partes de um domínio ou por completo. Se não especificado, o cookie irá ser retornado somente para o servidor que foi criado.
-path partes de uma URL no servidor atual. O cookie será retornado para todas URLs iniciando com o path especificado. Se não for especificado, o padrão é '/', para retornar o cookie para todas as páginas do seu site.
-secure Se definido com um valor positivo o browser retornará o cookie somente quando um protocolo de criptografia estiver em uso.
Para compatibilidade com Apache::Cookie, você pode opcionalmente passar um objeto da requisição do mod_perl como o primeiro argumento para new(). Isso será ignorado:
my $c = new CGI::Cookie($r,
-name => 'foo',
-value => ['bar','baz']
);
Enviando o cookie para o browser
A maneira mais simples de emitir um cookie ao browser é chamando o método bake():
Com o mod_perl, passe o objeto da requisição:
Se você mesmo quiser setar o cookie, dentro de um script CGI você pode emitir o cookie ao browser criando um ou mais Set-cookie no cabeçalho HTTP. Veja uma sequência típica:
my $c = new CGI::Cookie(-name => 'foo',
-value => ['bar','baz'],
-expires => '+3M'
);
print "Set-Cookie: $c\n";
print "Content-Type: text/html\n\n";
Para enviar mais de um cookie, crie vários Set-Cookie.
Se você está usando CGI.pm, você envia os cookies através de -cookie no argumento do método header():
print header
(-cookie=>
$c);
Usuários do Mod_perl podem setar cookies usando o objeto de requisição no método header_out():
$r->headers_out->set('Set-Cookie' => $c);
Internamente, cookies sobrecarrega o operador '' para chamar seu método as_string() quando incorporado no cabeçalho HTTP. as_string() torna os cookies em uma representação no RFC-compliant text representation. Você mesmo pode chamar as_string() se preferir:
print "Set-Cookie: " ,
$c->
as_string ,
"\n";
Recuperando cookies
%cookies = fetch CGI::Cookie;
fetch retorna uma lista associativa constando todos os cookies retornados do browser. A chave da array são os nomes dos cookies. Você pode iterar cookies desta maneira:
foreach (keys %cookies) { do_something($cookies{$_});
}
No contexto escalar, fetch() retorna um hash, que pode ser mais eficiente se você estiver manipulando múltiplos coookies.
CGI.om usa os métodos escapando a url para salvar e recuperar caracteres reservados em seus cookies. Se você tentar receber um cookie setado por um server secundário, este método escapando pode enganar você. Use preferivelmente o raw_fetch(), que tem a mesma semântica que o fetch(), mas não executando nenhum unescaping.
Você pode também recuperar cookies que foram armazenados em algum formulário externo usando o método parser() da classe:
$COOKIES = `cat /usr/tmp/Cookie_stash`;
%cookies = parse CGI::Cookie($COOKIES);
Se você estiver em um ambiente do mod_perl, você pode salvar algumas por cima passando o objeto de requisição para o fetch() como este:
Manipulando cookies
Os objetos cookies tem uma série de métodos de accesso para obter e setar atributos para o cookie. Cada accessor tem uma sintaxe similar. Chamado sem argumentos, o accessor retorna o valor atual do atributo. Chamado com um argumento, o accessor muda o atributo e retorna seu valor novo.
name()
Obtem ou seta o nome do cookie. Exemplo:
$name = $c->name;
$new_name = $c->name('fred');
value()
Obtem ou seta o valor do cookie. Exemplo:
$value = $c->value;
@new_value = $c->value(['a','b','c','d']);
value() é case-sensitive. No contexto de uma lista ele irá retorna o atual valor do cookie como um array. Em um contexto escalar ele irá retornar o primeiro valor de um cookie com multi-valores.
domain()
Obtem ou seta o domain do cookie.
path()
Obtem ou seta o path do cookie.
expires()
Obtem ou seta o tempo de expiração do cookie.
