/ 
CGIS-1.6
River stage zero No dependents
/ CGIS

NAME

CGIS - Session enabled CGI.pm

SYNOPSIS

use CGIS;

$cgi = new CGIS;
my $first_name = $cgi->session("f_name");

# use it the way you have been using CGI.pm

DESCRIPTION

CGIS is a simple, session-enabled extension for Lincoln Stein's CGI. Instead of loading CGI, you load CGIS, and use it the way you have been using CGI.pm, without any exceptions.

In addition, CGIS provides session() method, to support persistent session management accross subsequent HTTP requests, and partially overrides header() method to ensure proper HTTP headers are sent out with valid session cookies.

CGIS also modifies your CGI environement by appending 'CGISESSID' parameter with session id as a value. It means, self_url() method (CGI) will print URL with session related data intact.

CGIS requires CGI::Session installed properly. Uses its CGI::Session::File driver, and stores session data in a designated directory created in your system's temporary folder.

METHODS

  • session() - if used without argument returns CGI::Session object. Extra arguments passed will be directly sent along to CGI::Session's param() methods and their values will be returned.

  • session_dir() - returns full path to a folder where your session data are stored

  • header() - the same as standard version of header() with session cookies prepended. You can override it if you want by passing your own "-cookie" option.

  • urlf() - returns formated URL with proper session data appended. Arguments should be in the form of a hash (or hashref), which will be treated as a set of key/value pairs generated as a query string. For example:

    my $home = $cgi->urlf(_cmd => 'read', message=>'1001');

    The above example generates a url similar to something like:

    /cgi-bin/script.cgi?_cmd=read&message=1001&CGISESSID=6d084d93399ce7c07926ca11843b9334

EXAMPLES

A tiny example of a cgi program can be found in examples/ folder of the distribution. You may as well be able to see it in action at http://www.handalak.com/cgi-bin/cgis This script simply displays your session id as well as sample outputs of urlf() and self_url() methods for you to have an idea.

In session management enabled sites, you most likely send proper session cookie to the user's browser at each request. Instead of doing it manual, simply call CGIS's header() method, as you would that of CGI.pm's:

print $cgi->header();

And you are guaranteed proper cookie's sent out to the user's computer.

STORING DATA IN THE SESSION

# store user's name in the session for later use:
$cgi->session("full_name", "Sherzod Ruzmetov");

# store user's email for later:
$cgi->session("email", 'sherzodr@cpan.org');

READING DATA OFF THE SESSION

my $full_name = $cgi->session("full_name");
my $email     = $cgi->session('email');
print qq~<a href="mailto:$email">$full_name</a>~;

GETTING CGI::Session OBJECT

For performing more sophisticated oprations, you may need to get underlying CGI::Session object directly. To do this, simply call session() with no arguments:

$session = $cgi->session();    

# set expiration ticker for session object
$session->expire("+10m");

For more tricks, consult CGI::Session manual.

AUTHOR

Sherzod B. Ruzmetov <sherzodr@cpan.org>

COPYRIGHT

This library is free software. You can modify and/or distribute it under the same terms as Perl itself.

SEE ALSO

CGI::Session, CGI