NAME

CGI::kSession - sessions manager for CGI

VERSION

kSession.pm v 0.5.3

Recent Changes:

        0.5.3
        - updated the documentation
        0.5.2
        - fix value containing '='
        0.5.1
        - ugly fix with existing session
        0.5 
        - lifetime
        - path,lifetime as arguments with new

DESCRIPTION

This module can be used anywhere you need sessions. As a session management module, it uses files with a configurable lifetime to handle your session data. For those of you familiar with PHP, you will notice that the session syntax is a little bit similar.

METHODS

The following public methods are availible:

$s = new CGI::kSession();

The constructor, this starts the ball rolling. It can take the following hash-style parameters:

        lifetime -      how long the session lasts, in seconds
        path     -      the directory where you want to store your session files
        id       -      if you want to give the session a non-random name, use this parameter as well

$s->start();

This creates a session or resumes an old one (could be used in conjunction with something like HTTP::Cookie). This will return '1' if this is a new session, and '0' if it's resuming an old one. If you defined no values in the 'new()' call, then the session will start with a default lifetime of 600 seconds, a path of /var/tmp, and a random string for an id.

$s->save_path();

Save the session path or, without an argument, return the current session path. Used with an argument, this performs the same thing as the 'path' parameter in the constructor.

$s->id();

If the session id exists, this will return the current session id - useful if you want to maintain state with a cookie! If you pass a parameter, it acts the same as new( id => 'some_session_name'), i.e., it creates a session with that id.

$s->register();

This takes a string as an arguement and basically tells the session object this: "Hey, this is a variable I'm thinking about associating with some data down the road. Hang onto it for me, and I'll let you know what I'm going to do with it". Once you register a variable name here, you can use it in 'set()' and 'get()'.

$s->is_registered();

Check to see if the function is registered. Returns '1' for true, '0' for false.

$s->unregister();

Tell the session jinn that you no longer want to use this variable, and it can go back in the bottle (the variable, not the jinn... you still want the jinn around until you call 'destroy()').

$s->set();

This is where you actually define your variables (once you have "reserved" them using 'register()'). This method takes two arguments: the first is the name of the variable that you registerd, and the second is the info you want to store in the variable.

$s->get();

This method allows you to access the data that you have saved in a session - just pass it the name of the variable that you 'set()'.

$s->unset();

Calling this method will wipe all the variables stored in your session.

$s->destroy();

This method deletes the session file, destroys all the evidence, and skips bail.

EXAMPLES

Session creation and destruction

 use strict;
 use CGI;
 use CGI::kSession;

    my $cgi = new CGI;
    print $cgi->header;

    my $s = new CGI::kSession(lifetime=>10,path=>"/home/user/sessions/",id=>$cgi->param("SID"));
    $s->start();
    # $s->save_path('/home/user/sessions/');

    # registered "zmienna1"
    $s->register("zmienna1");
    $s->set("zmienna1","wartosc1");
    print $s->get("zmienna1"); #should print out "wartosc1"

    if ($s->is_registered("zmienna1")) {
        print "Is registered";
        } else {
        print "Not registered";
        }

    # unregistered "zmienna1"
    $s->unregister("zmienna1");
    $s->set("zmienna1","wartosc2");
    print $s->get("zmienna1"); #should print out -1
    
    $s->unset(); # unregister all variables
    $s->destroy(); # delete session with this ID

Marcin Krzyzanowski

Sessions, URLs, and Cookies

 use strict;
 use CGI;
 use CGI::Carp qw(fatalsToBrowser);
 use CGI::kSession;
 use CGI::Cookie;

    my $cgi = new CGI;
    my $last_sid = $cgi->param("SID");
    my $c = new CGI::Cookie(-name=>'SID',-value=>$last_sid);
    my ($id, $key, $value);

    my $s = new CGI::kSession(path=>"/tmp/");

    print $cgi->header(-cookie=>$c);

    print $cgi->start_html();

    if ($last_sid) {
        # note: the following I used for mozilla - your mileage may vary
        my $cookie_sid = (split/[=;]/, (fetch CGI::Cookie)->{SID})[1];

        if ($cookie_sid) {
            print "<b>We are now reading from the cookie:</b><p>";
            $id = $s->id($cookie_sid);
            $s->start($cookie_sid);
            print "The cookie's id: $cookie_sid<br>";
            print "Here's the test_value: ".$s->get("test_key")."<br>";
        } else {
            print "<b>We are now reading from the URL parameters:</b><p>";
            $id = $s->id($last_sid);
            $s->start($last_sid);
            print "Last page's id: $last_sid<br>";
            print "Here's the test_value: ".$s->get("test_key")."<br>";
        }
    } else {
        print "<b>Here we will set the session values:</b><p>";
        $s->start();
        $id = $s->id();
        print "My session id: $id<br>";
        $s->register("test_key");
        $s->set("test_key", "Oh, what a wonderful test_value this is...");
        print "Here's the test_value: ".$s->get("test_key")."<br>";
    }

    # note: the first click will set the session id from the URL the
    #           second click will retrieve a value from the cookie

    print "<a href=".(split/\//,$0)[-1]."?SID=$id>Next page</a>";
    print $cgi->end_html();

Duncan McGreggor

COPYRIGHT

Copyright 2000-2002 Marcin Krzyzanowski

AUTHOR

Marcin Krzyzanowski <krzak at linux.net.pl> http://krzak.linux.net.pl/

Duncan McGreggor <oubiwann at yahoo.com>