view release on metacpan or  search on metacpan

lib/CGI/Session/Tutorial.pm  view on Meta::CPAN

# $Id$

$CGI::Session::Tutorial::VERSION = '4.43';

=pod

=head1 NAME

CGI::Session::Tutorial - Extended CGI::Session manual

=head1 STATE MAINTENANCE OVERVIEW

Since HTTP is a stateless protocol, each subsequent click to a web site is treated as new request by the Web server. The server does not relate a visit with a previous one, thus all the state information from the previous requests are lost. This make...

For our rescue come such technologies as I<HTTP Cookies> and I<QUERY_STRING>s that help us save the users' session for a certain period. Since I<HTTP Cookies> and I<QUERY_STRING>s alone cannot take us too far (B<RFC 2965, Section 5, "Implementation L...

Before we discuss this library, let's look at some alternative solutions.

=head2 COOKIE

Cookie is a piece of text-information that a web server is entitled to place in the user's hard disk, assuming a user agent (such as Internet Explorer, Mozilla, etc) is compatible with the specification. After the cookie is placed, user agents are re...

Although I<HTTP Cookies> seem to be promising solution for the statelessness of HTTP, they do carry certain limitations, such as limited number of cookies per domain and per user agent and limited size on each cookie. User Agents are required to stor...

=head2 QUERY STRING

Query string is a string appended to URL following a question mark (?) such as:

    http://my.dot.com/login.cgi?user=sherzodr;password=top-secret

As you probably guessed, it can also help you pass state information from a click to another, but how secure is it do you think, considering these URLs tend to get cached by most of the user agents and also logged in the servers access log, to which ...

=head2 HIDDEN FIELDS

Hidden field is another alternative to using query strings and they come in two flavors: hidden fields used in POST methods and the ones in GET. The ones used in GET methods will turn into a true query strings once submitted, so all the disadvantages...

Query strings and hidden fields are also lost easily by closing the browser, or by clicking the browser's "Back" button.

=head2 SERVER SIDE SESSION MANAGEMENT

This technique is built upon the aforementioned technologies plus a server-side storage device, which saves the state data on the server side. Each session has a unique id associated with the data in the server. This id is also associated with the us...

Advantages:

=over 4

=item *

We no longer need to depend on User Agent constraints in cookie size.

=item *

Sensitive data no longer need to be traveling across the network at each request (which is the case with query strings, cookies and hidden fields). The only thing that travels is the unique id generated for the session (B<5767393932698093d0b75ef61437...

=item *

User will not have sensitive data stored in his/her computer in unsecured file (which is a cookie file).

=item *

It's possible to handle very big and even complex data structures transparently (which I<HTTP Cookies> do not handle).

=back

That's what CGI::Session is all about - implementing server side session management. Now is a good time to get feet wet.

=head1 PROGRAMMING STYLE

Server side session management system might be seeming awfully convoluted if you have never dealt with it. Fortunately, with L<CGI::Session|CGI::Session> all the complexity is handled by the library transparently. This section of the manual can be tr...

All applications making use of server side session management rely on the following pattern of operation regardless of the way the system is implemented:

=over 4

=item 1

Check if the user has session cookie dropped in his computer from previous request

=item 2

If the cookie does not exist, create a new session identifier, and drop it as cookie to the user's computer.

=item 3

If session cookie exists, read the session ID from the cookie and load any previously saved session data from the server side storage. If session had any expiration date set it's useful to re-drop the same cookie to the user's computer so its expirat...

=item 4

Store any necessary data in the session that you want to make available for the next HTTP request.

=back

CGI::Session will handle all of the above steps. All you have to do is to choose what to store in the session.

=head2 GETTING STARTED

To make L<CGI::Session|CGI::Session>'s functionality available in your program do either of the following somewhere on top of your program file:

    use CGI::Session;
    # or
    require CGI::Session;

Whenever you're ready to create a new session in your application, do the following:

    $session = CGI::Session->new () or die CGI::Session->errstr;

Above line will first try to re-initialize an existing session by consulting cookies and necessary QUERY_STRING parameters. If it fails will create a brand new session with a unique ID, which is normally called I<session ID>, I<SID> for short, and ca...

We didn't check for any session cookies above, did we? No, we didn't, but CGI::Session did. It looked for a cookie called C<CGISESSID>, and if it found it tried to load existing session from server side storage (B<file> in our case). If cookie didn't...

NOTE: For the above syntax to work as intended your application needs to have write access to your computer's I<TEMPDIR> folder, which is usually F</tmp> in UNIX. If it doesn't, or if you wish to store this application's session files in a different ...

    $session = CGI::Session->new(undef, undef, {Directory=>'../tmp/sessions'});

Now it will store all the newly created sessions in (and will attempt to initialize requested sessions from) that folder. Don't worry if the directory hierarchy you want to use doesn't already exist. It will be created for you. For details on how ses...

There is one small, but very important thing your application needs to perform after creating CGI::Session object as above. It needs to drop Session ID as an I<HTTP cookie> into the user's computer. CGI::Session will use this cookie to identify the u...

To make sure CGI::Session will be able to read your cookie at next request you need to consult its C<name()> method for cookie's suggested name:

    $cookie = $query->cookie( -name   => $session->name,
                              -value  => $session->id );
    print $query->header( -cookie=>$cookie );

C<name()> returns C<CGISESSID> by default. If you prefer a different cookie name, you can change it as easily too, but you have to do it before CGI::Session object is created:

    CGI::Session->name("SID");
    $session = CGI::Session->new();