NAME
CGI::Cookie::Pack - Pack in/out a large number of parameters to a small number of cookies.
SYNOPSIS
use CGI::Cookie::Pack;
# send cookies over HTTP which have composed parameters.
@cookie = CGI::Cookie::Pack->packin(
name => 'packed',
param => [
name => 'Masanori HATA' ,
mail => 'lovewing@dream.big.or.jp',
sex => 'male' ,
birth => '2003-04-09' ,
nation => 'Japan' ,
pref => 'Saitama' ,
city => 'Kawaguchi' ,
tel => '+81-48-2XX-XXXX' ,
fax => '+81-48-2XX-XXXX' ,
job => 'student' ,
role => 'president' ,
hobby => 'exaggeration' ,
],
);
foreach my $cookie (@cookie) {
print "Set-Cookie: $cookie\n";
}
print "Content-Type: text/html\n\n";
# receive cookies over HTTP and get decomposed parameters.
%param = CGI::Cookie::Pack->packout;
DESCRIPTION
With this module HTTP Cookie can transport more parameters than usual. In the ordinary way, a cookie can content one NAME and VALUE pair, then the combined NAME and VALUE string have size limit of 4096 bytes. In addition to that, there can be 20 cookies at most per server of domain. So in short, it can store only 20 parameters! Creation of this module is to intend to break through that limit.
METHODS
- packin(name => $name, param => [%param])
-
Object-Class method. This method internally using new(), name(), param(), monolith() and compose() methods. Simply using this method specified with some arguments, you will get packed combined NAME and VALUE string(s).
The arguments,
name
andparam
is not omittable. Value ofparam
argument must quoted by the square brackets to pass its anonymous reference as an array (however, you can use hash in the brackets).Argument
monolith
is optional. If you would compose a monolithic cookie even if it excessed 4096 bytes limit, give value ofmonolith
a positive number.packin(name => $name, param => [%param], monlith => 1)
- packout()
-
Object-Class method. This method internally using new(), monolith() and decompose() methods. Simply using this method specified with some arguments, you will get unpacked parameters.
Argument
monolith
is optional. If you would decompose a monolithic composed cookie, you must give value ofmonolith
a positive number. - new()
-
Class method. Constructor.
- name($name)
-
Object method. Give name to the composed cookie.
- param(@param)
-
Object method. Give parameters to compose.
- monolith($num)
-
Object method. If you give a positive number, cookie will compose/decompose as a monolithic one. If you give 0 (default) or a negative number, cookie will not compose/decompose as a monolithic one.
- compose()
-
Object method. Compose cookie(s).
The algorithm is realized by twice character escape. First,
NAME
andVALUE
strings are PEA escaped. PEA escape is escape "%", "=" and "&" characters to "%P", "%E" and "%A" character squences. Then, eachNAME
andVALUE
are paired with "=" character, and these allNAME=VALUE
pairs are joined with "&" character to a string. Second, the name of cookie (be given by name() method) and the joinedNAME=VALUE
pairs string are uri-escaped, and then each uri-escaped strings are paired with "=" character.If total size of the string excess 4096 bytes limit, the string is splitted to some cookies. Names of each splitted cookies are serialized by following "_" (underbar character) and two digit number. That is, names of cookies are to become like
$name_XX
. Note that still in a case total size of the string do not excess 4096 byte limit, name of the cookie has serial number ($name_00
).Exceptionally, under monolith mode, splitting won't do. Also cookie name serializing won't.
- decompose()
-
Object method. Decompose parameters from composed cookie(s).
The algorithm is the reversed procedure of composing. First, take out uri-escaped string from splitted cookies in $ENV{'HTTP_COOKIE'}, and then uri-unescape it. Second, extract from that uri_unescaped string to
NAME
andVALUE
pairs, and then PEA unescape them.You could implement the above procedure also at the client side with JavaScript.
Note that monolith mode would affect decomposing procedure, too.
-
Exportable function. This function returns date-time string which is formatted with Netscape Cookie Specification http://wp.netscape.com/newsref/std/cookie_spec.html.
$unix_time
is offset in seconds from the unix epoch time (1970-01-01 00:00:00 UTC).
SEE ALSO
- RFC 2965: http://www.ietf.org/rfc/rfc2965.txt (Cookie)
- HTML 4: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1 (uri-encode)
AUTHOR
Masanori HATA http://go.to/hata (Saitama, JAPAN)
COPYRIGHT
Copyright (c) 2003-2005 Masanori HATA. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 361:
You forgot a '=back' before '=head1'