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, you will get unpacked parameters. You may utilize unpacked parameters to input into a hash (%).

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 simple as CGI::Cookie do. First, all strings of parameters (both of KEY and VALUE) are uri-escaped. By uri-escape, most of sign characters (including "&" sign) are escaped to "%HH" string. While that, "&" sign can be safely used in "Set-Cookie: " HTTP header because it is a "token" character (for the definition of "token", refer to RFC 2616 http://www.ietf.org/rfc/rfc2616.txt). So second, all uri-escaped parameters (both of KEY and VALUE) are joined by "&" sign as separator to make a single string. Third, at last, name of cookie (of course it is also uri-escaped) and that united string are combined by "=" sign as separater.

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 united string from splitted cookies in $ENV{'HTTP_COOKIE'}, and then separate it to individual parameters. Second, uri-unescape all strings of parameters (both of KEY and VALUE).

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.