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 and param is not omittable. Value of param 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 of monolith 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 of monolith 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 and VALUE strings are PEA escaped. PEA escape is escape "%", "=" and "&" characters to "%P", "%E" and "%A" character squences. Then, each NAME and VALUE are paired with "=" character, and these all NAME=VALUE pairs are joined with "&" character to a string. Second, the name of cookie (be given by name() method) and the joined NAME=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 and VALUE 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.

datetime_cookie($unix_time)

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

Netscape: http://wp.netscape.com/newsref/std/cookie_spec.html (Cookie)

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.