data/TWiki/CGISessionDotPm.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
head	1.1;
colas@0
     2
access;
colas@0
     3
symbols;
colas@0
     4
locks; strict;
colas@0
     5
comment	@# @;
colas@0
     6
colas@0
     7
colas@0
     8
1.1
colas@0
     9
date	2008.01.22.03.21.31;	author TWikiContributor;	state Exp;
colas@0
    10
branches;
colas@0
    11
next	;
colas@0
    12
colas@0
    13
colas@0
    14
desc
colas@0
    15
@buildrelease
colas@0
    16
@
colas@0
    17
colas@0
    18
colas@0
    19
1.1
colas@0
    20
log
colas@0
    21
@buildrelease
colas@0
    22
@
colas@0
    23
text
colas@0
    24
@---+ Package ==
colas@0
    25
*extends* <tt>CGI::Session::ErrorHandler </tt>
colas@0
    26
colas@0
    27
colas@0
    28
%TOC%
colas@0
    29
=head1 NAME
colas@0
    30
colas@0
    31
CGI::Session - persistent session data in CGI applications
colas@0
    32
colas@0
    33
=head1 SYNOPSIS
colas@0
    34
colas@0
    35
    # Object initialization:
colas@0
    36
    use CGI::Session;
colas@0
    37
    $session = new CGI::Session();
colas@0
    38
colas@0
    39
    $CGISESSID = $session->id();
colas@0
    40
colas@0
    41
    # send proper HTTP header with cookies:
colas@0
    42
    print $session->header();
colas@0
    43
colas@0
    44
    # storing data in the session
colas@0
    45
    $session->param('f_name', 'Sherzod');
colas@0
    46
    # or
colas@0
    47
    $session->param(-name=>'l_name', -value=>'Ruzmetov');
colas@0
    48
colas@0
    49
    # flush the data from memory to the storage driver at least before your
colas@0
    50
    # program finishes since auto-flushing can be unreliable
colas@0
    51
    $session->flush();
colas@0
    52
colas@0
    53
    # retrieving data
colas@0
    54
    my $f_name = $session->param('f_name');
colas@0
    55
    # or
colas@0
    56
    my $l_name = $session->param(-name=>'l_name');
colas@0
    57
colas@0
    58
    # clearing a certain session parameter
colas@0
    59
    $session->clear(["l_name", "f_name"]);
colas@0
    60
colas@0
    61
    # expire '_is_logged_in' flag after 10 idle minutes:
colas@0
    62
    $session->expire('is_logged_in', '+10m')
colas@0
    63
colas@0
    64
    # expire the session itself after 1 idle hour
colas@0
    65
    $session->expire('+1h');
colas@0
    66
colas@0
    67
    # delete the session for good
colas@0
    68
    $session->delete();
colas@0
    69
colas@0
    70
=head1 DESCRIPTION
colas@0
    71
colas@0
    72
CGI-Session is a Perl5 library that provides an easy, reliable and modular session management system across HTTP requests.
colas@0
    73
Persistency is a key feature for such applications as shopping carts, login/authentication routines, and application that
colas@0
    74
need to carry data across HTTP requests. CGI::Session does that and many more.
colas@0
    75
colas@0
    76
=head1 TRANSLATIONS
colas@0
    77
colas@0
    78
This document is also available in Japanese.
colas@0
    79
colas@0
    80
=over 4
colas@0
    81
colas@0
    82
=item o 
colas@0
    83
colas@0
    84
Translation based on 4.14: http://digit.que.ne.jp/work/index.cgi?Perldoc/ja
colas@0
    85
colas@0
    86
=item o
colas@0
    87
colas@0
    88
Translation based on 3.11, including Cookbook and Tutorial: http://perldoc.jp/docs/modules/CGI-Session-3.11/
colas@0
    89
colas@0
    90
=back
colas@0
    91
colas@0
    92
=head1 TO LEARN MORE
colas@0
    93
colas@0
    94
Current manual is optimized to be used as a quick reference. To learn more both about the philosophy and CGI::Session
colas@0
    95
programming style, consider the following:
colas@0
    96
colas@0
    97
=over 4
colas@0
    98
colas@0
    99
=item *
colas@0
   100
colas@0
   101
L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual. Also includes library architecture and driver specifications.
colas@0
   102
colas@0
   103
=item *
colas@0
   104
colas@0
   105
We also provide mailing lists for CGI::Session users. To subscribe to the list or browse the archives visit https://lists.sourceforge.net/lists/listinfo/cgi-session-user
colas@0
   106
colas@0
   107
=item *
colas@0
   108
colas@0
   109
B<RFC 2965> - "HTTP State Management Mechanism" found at ftp://ftp.isi.edu/in-notes/rfc2965.txt
colas@0
   110
colas@0
   111
=item *
colas@0
   112
colas@0
   113
L<CGI|CGI> - standard CGI library
colas@0
   114
colas@0
   115
=item *
colas@0
   116
colas@0
   117
L<Apache::Session|Apache::Session> - another fine alternative to CGI::Session.
colas@0
   118
colas@0
   119
=back
colas@0
   120
colas@0
   121
=head1 METHODS
colas@0
   122
colas@0
   123
Following is the overview of all the available methods accessible via CGI::Session object.
colas@0
   124
colas@0
   125
=head2 new()
colas@0
   126
colas@0
   127
=head2 new( $sid )
colas@0
   128
colas@0
   129
=head2 new( $query )
colas@0
   130
colas@0
   131
=head2 new( $dsn, $query||$sid )
colas@0
   132
colas@0
   133
=head2 new( $dsn, $query||$sid, \%dsn_args )
colas@0
   134
colas@0
   135
Constructor. Returns new session object, or undef on failure. Error message is accessible through L<errstr() - class method|CGI::Session::ErrorHandler/errstr>. If called on an already initialized session will re-initialize the session based on already configured object. This is only useful after a call to L<load()|/"load">.
colas@0
   136
colas@0
   137
Can accept up to three arguments, $dsn - Data Source Name, $query||$sid - query object OR a string representing session id, and finally, \%dsn_args, arguments used by $dsn components.
colas@0
   138
colas@0
   139
If called without any arguments, $dsn defaults to I<driver:file;serializer:default;id:md5>, $query||$sid defaults to C<< CGI->new() >>, and C<\%dsn_args> defaults to I<undef>.
colas@0
   140
colas@0
   141
If called with a single argument, it will be treated either as C<$query> object, or C<$sid>, depending on its type. If argument is a string , C<new()> will treat it as session id and will attempt to retrieve the session from data store. If it fails, will create a new session id, which will be accessible through L<id() method|/"id">. If argument is an object, L<cookie()|CGI/cookie> and L<param()|CGI/param> methods will be called on that object to recover a potential C<$sid> and retrieve it from data store. If it fails, C<new()> will create a new session id, which will be accessible through L<id() method|/"id">. C<name()> will define the name of the query parameter and/or cookie name to be requested, defaults to I<CGISESSID>.
colas@0
   142
colas@0
   143
If called with two arguments first will be treated as $dsn, and second will be treated as $query or $sid or undef, depending on its type. Some examples of this syntax are:
colas@0
   144
colas@0
   145
    $s = CGI::Session->new("driver:mysql", undef);
colas@0
   146
    $s = CGI::Session->new("driver:sqlite", $sid);
colas@0
   147
    $s = CGI::Session->new("driver:db_file", $query);
colas@0
   148
    $s = CGI::Session->new("serializer:storable;id:incr", $sid);
colas@0
   149
    # etc...
colas@0
   150
colas@0
   151
colas@0
   152
Following data source components are supported:
colas@0
   153
colas@0
   154
=over 4
colas@0
   155
colas@0
   156
=item *
colas@0
   157
colas@0
   158
B<driver> - CGI::Session driver. Available drivers are L<file|CGI::Session::Driver::file>, L<db_file|CGI::Session::Driver::db_file>, L<mysql|CGI::Session::Driver::mysql> and L<sqlite|CGI::Session::Driver::sqlite>. Third party drivers are welcome. For driver specs consider L<CGI::Session::Driver|CGI::Session::Driver>
colas@0
   159
colas@0
   160
=item *
colas@0
   161
colas@0
   162
B<serializer> - serializer to be used to encode the data structure before saving
colas@0
   163
in the disk. Available serializers are L<storable|CGI::Session::Serialize::storable>, L<freezethaw|CGI::Session::Serialize::freezethaw> and L<default|CGI::Session::Serialize::default>. Default serializer will use L<Data::Dumper|Data::Dumper>.
colas@0
   164
colas@0
   165
=item *
colas@0
   166
colas@0
   167
B<id> - ID generator to use when new session is to be created. Available ID generator is L<md5|CGI::Session::ID::md5>
colas@0
   168
colas@0
   169
=back
colas@0
   170
colas@0
   171
For example, to get CGI::Session store its data using DB_File and serialize data using FreezeThaw:
colas@0
   172
colas@0
   173
    $s = new CGI::Session("driver:DB_File;serializer:FreezeThaw", undef);
colas@0
   174
colas@0
   175
If called with three arguments, first two will be treated as in the previous example, and third argument will be C<\%dsn_args>, which will be passed to C<$dsn> components (namely, driver, serializer and id generators) for initialization purposes. Since all the $dsn components must initialize to some default value, this third argument should not be required for most drivers to operate properly.
colas@0
   176
colas@0
   177
undef is acceptable as a valid placeholder to any of the above arguments, which will force default behavior.
colas@0
   178
colas@0
   179
=head2 load()
colas@0
   180
colas@0
   181
=head2 load($query||$sid)
colas@0
   182
colas@0
   183
=head2 load($dsn, $query||$sid)
colas@0
   184
colas@0
   185
=head2 load($dsn, $query, \%dsn_args);
colas@0
   186
colas@0
   187
Accepts the same arguments as new(), and also returns a new session object, or
colas@0
   188
undef on failure.  The difference is, L<new()|/"new"> can create new session if
colas@0
   189
it detects expired and non-existing sessions, but C<load()> does not.
colas@0
   190
colas@0
   191
C<load()> is useful to detect expired or non-existing sessions without forcing the library to create new sessions. So now you can do something like this:
colas@0
   192
colas@0
   193
    $s = CGI::Session->load() or die CGI::Session->errstr();
colas@0
   194
    if ( $s->is_expired ) {
colas@0
   195
        print $s->header(),
colas@0
   196
            $cgi->start_html(),
colas@0
   197
            $cgi->p("Your session timed out! Refresh the screen to start new session!")
colas@0
   198
            $cgi->end_html();
colas@0
   199
        exit(0);
colas@0
   200
    }
colas@0
   201
colas@0
   202
    if ( $s->is_empty ) {
colas@0
   203
        $s = $s->new() or die $s->errstr;
colas@0
   204
    }
colas@0
   205
colas@0
   206
Notice, all I<expired> sessions are empty, but not all I<empty> sessions are expired!
colas@0
   207
colas@0
   208
colas@0
   209
=head2 id()
colas@0
   210
colas@0
   211
Returns effective ID for a session. Since effective ID and claimed ID can differ, valid session id should always
colas@0
   212
be retrieved using this method.
colas@0
   213
colas@0
   214
=head2 param($name)
colas@0
   215
colas@0
   216
=head2 param(-name=E<gt>$name)
colas@0
   217
colas@0
   218
Used in either of the above syntax returns a session parameter set to $name or undef if it doesn't exist. If it's called on a deleted method param() will issue a warning but return value is not defined.
colas@0
   219
colas@0
   220
=head2 param($name, $value)
colas@0
   221
colas@0
   222
=head2 param(-name=E<gt>$name, -value=E<gt>$value)
colas@0
   223
colas@0
   224
Used in either of the above syntax assigns a new value to $name parameter,
colas@0
   225
which can later be retrieved with previously introduced param() syntax. C<$value>
colas@0
   226
may be a scalar, arrayref or hashref.
colas@0
   227
colas@0
   228
Attempts to set parameter names that start with I<_SESSION_> will trigger
colas@0
   229
a warning and undef will be returned.
colas@0
   230
colas@0
   231
=head2 param_hashref()
colas@0
   232
colas@0
   233
B<Deprecated>. Use L<dataref()|/"dataref"> instead.
colas@0
   234
colas@0
   235
=head2 dataref()
colas@0
   236
colas@0
   237
Returns reference to session's data table:
colas@0
   238
colas@0
   239
    $params = $s->dataref();
colas@0
   240
    $sid = $params->{_SESSION_ID};
colas@0
   241
    $name= $params->{name};
colas@0
   242
    # etc...
colas@0
   243
colas@0
   244
Useful for having all session data in a hashref, but too risky to update.
colas@0
   245
colas@0
   246
=head2 save_param()
colas@0
   247
colas@0
   248
=head2 save_param($query)
colas@0
   249
colas@0
   250
=head2 save_param($query, \@@list)
colas@0
   251
colas@0
   252
Saves query parameters to session object. In other words, it's the same as calling L<param($name, $value)|/"param"> for every single query parameter returned by C<< $query->param() >>. The first argument, if present, should be either CGI object or any object which can provide param() method. If it's undef, defaults to the return value of L<query()|/"query">, which returns C<< CGI->new >>. If second argument is present and is a reference to an array, only those query parameters found in the array will be stored in the session. undef is a valid placeholder for any argument to force default behavior.
colas@0
   253
colas@0
   254
=head2 load_param()
colas@0
   255
colas@0
   256
=head2 load_param($query)
colas@0
   257
colas@0
   258
=head2 load_param($query, \@@list)
colas@0
   259
colas@0
   260
Loads session parameters into a query object. The first argument, if present, should be query object, or any other object which can provide param() method. If second argument is present and is a reference to an array, only parameters found in that array will be loaded to the query object.
colas@0
   261
colas@0
   262
=head2 clear()
colas@0
   263
colas@0
   264
=head2 clear('field')
colas@0
   265
colas@0
   266
=head2 clear(\@@list)
colas@0
   267
colas@0
   268
Clears parameters from the session object.
colas@0
   269
colas@0
   270
With no parameters, all fields are cleared. If passed a single parameter or a
colas@0
   271
reference to an array, only the named parameters are cleared.
colas@0
   272
colas@0
   273
=head2 flush()
colas@0
   274
colas@0
   275
Synchronizes data in memory  with the copy serialized by the driver. Call flush() 
colas@0
   276
if you need to access the session from outside the current session object. You should
colas@0
   277
at least call flush() before your program exits. 
colas@0
   278
colas@0
   279
As a last resort, CGI::Session will automatically call flush for you just
colas@0
   280
before the program terminates or session object goes out of scope. This automatic
colas@0
   281
behavior was the recommended behavior until the 4.x series. Automatic flushing
colas@0
   282
has since proven to be unreliable, and in some cases is now required in places
colas@0
   283
that worked with 3.x. For further details see:
colas@0
   284
colas@0
   285
 http://rt.cpan.org/Ticket/Display.html?id=17541
colas@0
   286
 http://rt.cpan.org/Ticket/Display.html?id=17299
colas@0
   287
colas@0
   288
=head2 atime()
colas@0
   289
colas@0
   290
Read-only method. Returns the last access time of the session in seconds from epoch. This time is used internally while
colas@0
   291
auto-expiring sessions and/or session parameters.
colas@0
   292
colas@0
   293
=head2 ctime()
colas@0
   294
colas@0
   295
Read-only method. Returns the time when the session was first created in seconds from epoch.
colas@0
   296
colas@0
   297
=head2 expire()
colas@0
   298
colas@0
   299
=head2 expire($time)
colas@0
   300
colas@0
   301
=head2 expire($param, $time)
colas@0
   302
colas@0
   303
Sets expiration interval relative to L<atime()|/"atime">.
colas@0
   304
colas@0
   305
If used with no arguments, returns the expiration interval if it was ever set. If no expiration was ever set, returns undef. For backwards compatibility, a method named C<etime()> does the same thing.
colas@0
   306
colas@0
   307
Second form sets an expiration time. This value is checked when previously stored session is asked to be retrieved, and if its expiration interval has passed, it will be expunged from the disk immediately. Passing 0 cancels expiration.
colas@0
   308
colas@0
   309
By using the third syntax you can set the expiration interval for a particular
colas@0
   310
session parameter, say I<~logged-in>. This would cause the library call clear()
colas@0
   311
on the parameter when its time is up. Note it only makes sense to set this value to 
colas@0
   312
something I<earlier> than when the whole session expires.  Passing 0 cancels expiration.
colas@0
   313
colas@0
   314
All the time values should be given in the form of seconds. Following keywords are also supported for your convenience:
colas@0
   315
colas@0
   316
    +-----------+---------------+
colas@0
   317
    |   alias   |   meaning     |
colas@0
   318
    +-----------+---------------+
colas@0
   319
    |     s     |   Second      |
colas@0
   320
    |     m     |   Minute      |
colas@0
   321
    |     h     |   Hour        |
colas@0
   322
    |     d     |   Day         |
colas@0
   323
    |     w     |   Week        |
colas@0
   324
    |     M     |   Month       |
colas@0
   325
    |     y     |   Year        |
colas@0
   326
    +-----------+---------------+
colas@0
   327
colas@0
   328
Examples:
colas@0
   329
colas@0
   330
    $session->expire("2h");                # expires in two hours
colas@0
   331
    $session->expire(0);                   # cancel expiration
colas@0
   332
    $session->expire("~logged-in", "10m"); # expires '~logged-in' parameter after 10 idle minutes
colas@0
   333
colas@0
   334
Note: all the expiration times are relative to session's last access time, not to its creation time. To expire a session immediately, call L<delete()|/"delete">. To expire a specific session parameter immediately, call L<clear([$name])|/"clear">.
colas@0
   335
colas@0
   336
colas@0
   337
=head2 is_new()
colas@0
   338
colas@0
   339
Returns true only for a brand new session.
colas@0
   340
colas@0
   341
=head2 is_expired()
colas@0
   342
colas@0
   343
Tests whether session initialized using L<load()|/"load"> is to be expired. This method works only on sessions initialized with load():
colas@0
   344
colas@0
   345
    $s = CGI::Session->load() or die CGI::Session->errstr;
colas@0
   346
    if ( $s->is_expired ) {
colas@0
   347
        die "Your session expired. Please refresh";
colas@0
   348
    }
colas@0
   349
    if ( $s->is_empty ) {
colas@0
   350
        $s = $s->new() or die $s->errstr;
colas@0
   351
    }
colas@0
   352
colas@0
   353
colas@0
   354
=head2 is_empty()
colas@0
   355
colas@0
   356
Returns true for sessions that are empty. It's preferred way of testing whether requested session was loaded successfully or not:
colas@0
   357
colas@0
   358
    $s = CGI::Session->load($sid);
colas@0
   359
    if ( $s->is_empty ) {
colas@0
   360
        $s = $s->new();
colas@0
   361
    }
colas@0
   362
colas@0
   363
Actually, the above code is nothing but waste. The same effect could've been achieved by saying:
colas@0
   364
colas@0
   365
    $s = CGI::Session->new( $sid );
colas@0
   366
colas@0
   367
L<is_empty()|/"is_empty"> is useful only if you wanted to catch requests for expired sessions, and create new session afterwards. See L<is_expired()|/"is_expired"> for an example.
colas@0
   368
colas@0
   369
=head2 delete()
colas@0
   370
colas@0
   371
Deletes a session from the data store and empties session data from memory, completely, so subsequent read/write requests on the same object will fail. Technically speaking, it will only set object's status to I<STATUS_DELETED> and will trigger L<flush()|/"flush">, and flush() will do the actual removal.
colas@0
   372
colas@0
   373
=head2 find( \&code )
colas@0
   374
colas@0
   375
=head2 find( $dsn, \&code )
colas@0
   376
colas@0
   377
=head2 find( $dsn, \&code, \%dsn_args )
colas@0
   378
colas@0
   379
Experimental feature. Executes \&code for every session object stored in disk, passing initialized CGI::Session object as the first argument of \&code. Useful for housekeeping purposes, such as for removing expired sessions. Following line, for instance, will remove sessions already expired, but are still in disk:
colas@0
   380
colas@0
   381
The following line, for instance, will remove sessions already expired, but which are still on disk:
colas@0
   382
colas@0
   383
    CGI::Session->find( sub {} );
colas@0
   384
colas@0
   385
Notice, above \&code didn't have to do anything, because load(), which is called to initialize sessions inside find(), will automatically remove expired sessions. Following example will remove all the objects that are 10+ days old:
colas@0
   386
colas@0
   387
    CGI::Session->find( \&purge );
colas@0
   388
    sub purge {
colas@0
   389
        my ($session) = @@_;
colas@0
   390
        next if $session->is_empty;    # <-- already expired?!
colas@0
   391
        if ( ($session->ctime + 3600*240) <= time() ) {
colas@0
   392
            $session->delete() or warn "couldn't remove " . $session->id . ": " . $session->errstr;
colas@0
   393
        }
colas@0
   394
    }
colas@0
   395
colas@0
   396
B<Note>: find will not change the modification or access times on the sessions it returns.
colas@0
   397
colas@0
   398
Explanation of the 3 parameters to C<find()>:
colas@0
   399
colas@0
   400
=over 4
colas@0
   401
colas@0
   402
=item $dsn
colas@0
   403
colas@0
   404
This is the DSN (Data Source Name) used by CGI::Session to control what type of
colas@0
   405
sessions you previously created and what type of sessions you now wish method
colas@0
   406
C<find()> to pass to your callback.
colas@0
   407
colas@0
   408
The default value is defined above, in the docs for method C<new()>, and is
colas@0
   409
'driver:file;serializer:default;id:md5'.
colas@0
   410
colas@0
   411
Do not confuse this DSN with the DSN arguments mentioned just below, under \%dsn_args.
colas@0
   412
colas@0
   413
=item \&code
colas@0
   414
colas@0
   415
This is the callback provided by you (i.e. the caller of method C<find()>)
colas@0
   416
which is called by CGI::Session once for each session found by method C<find()>
colas@0
   417
which matches the given $dsn.
colas@0
   418
colas@0
   419
There is no default value for this coderef.
colas@0
   420
colas@0
   421
When your callback is actually called, the only parameter is a session. If you
colas@0
   422
want to call a subroutine you already have with more parameters, you can
colas@0
   423
achieve this by creating an anonymous subroutine that calls your subroutine
colas@0
   424
with the parameters you want. For example:
colas@0
   425
colas@0
   426
    CGI::Session->find($dsn, sub { my_subroutine( @@_, 'param 1', 'param 2' ) } );
colas@0
   427
    CGI::Session->find($dsn, sub { $coderef->( @@_, $extra_arg ) } );
colas@0
   428
    
colas@0
   429
Or if you wish, you can define a sub generator as such:
colas@0
   430
colas@0
   431
    sub coderef_with_args {
colas@0
   432
        my ( $coderef, @@params ) = @@_;
colas@0
   433
        return sub { $coderef->( @@_, @@params ) };
colas@0
   434
    }
colas@0
   435
    
colas@0
   436
    CGI::Session->find($dsn, coderef_with_args( $coderef, 'param 1', 'param 2' ) );
colas@0
   437
colas@0
   438
=item \%dsn_args
colas@0
   439
colas@0
   440
If your $dsn uses file-based storage, then this hashref might contain keys such as:
colas@0
   441
colas@0
   442
    {
colas@0
   443
        Directory => Value 1,
colas@0
   444
        NoFlock   => Value 2,
colas@0
   445
        UMask     => Value 3
colas@0
   446
    }
colas@0
   447
colas@0
   448
If your $dsn uses db-based storage, then this hashref contains (up to) 3 keys, and looks like:
colas@0
   449
colas@0
   450
    {
colas@0
   451
        DataSource => Value 1,
colas@0
   452
        User       => Value 2,
colas@0
   453
        Password   => Value 3
colas@0
   454
    }
colas@0
   455
colas@0
   456
These 3 form the DSN, username and password used by DBI to control access to your database server,
colas@0
   457
and hence are only relevant when using db-based sessions.
colas@0
   458
colas@0
   459
The default value of this hashref is undef.
colas@0
   460
colas@0
   461
=back
colas@0
   462
colas@0
   463
B<Note:> find() is meant to be convenient, not necessarily efficient. It's best suited in cron scripts.
colas@0
   464
colas@0
   465
=head1 MISCELLANEOUS METHODS
colas@0
   466
colas@0
   467
=head2 remote_addr()
colas@0
   468
colas@0
   469
Returns the remote address of the user who created the session for the first time. Returns undef if variable REMOTE_ADDR wasn't present in the environment when the session was created.
colas@0
   470
colas@0
   471
colas@0
   472
=head2 errstr()
colas@0
   473
colas@0
   474
Class method. Returns last error message from the library.
colas@0
   475
colas@0
   476
=head2 dump()
colas@0
   477
colas@0
   478
Returns a dump of the session object. Useful for debugging purposes only.
colas@0
   479
colas@0
   480
=head2 header()
colas@0
   481
colas@0
   482
Replacement for L<CGI.pm|CGI>'s header() method. Without this method, you usually need to create a CGI::Cookie object and send it as part of the HTTP header:
colas@0
   483
colas@0
   484
    $cookie = CGI::Cookie->new(-name=>$session->name, -value=>$session->id);
colas@0
   485
    print $cgi->header(-cookie=>$cookie);
colas@0
   486
colas@0
   487
You can minimize the above into:
colas@0
   488
colas@0
   489
    print $session->header();
colas@0
   490
colas@0
   491
It will retrieve the name of the session cookie from C<$session->name()> which defaults to C<$CGI::Session::NAME>. If you want to use a different name for your session cookie, do something like following before creating session object:
colas@0
   492
colas@0
   493
    CGI::Session->name("MY_SID");
colas@0
   494
    $session = new CGI::Session(undef, $cgi, \%attrs);
colas@0
   495
colas@0
   496
Now, $session->header() uses "MY_SID" as a name for the session cookie.
colas@0
   497
colas@0
   498
=head2 query()
colas@0
   499
colas@0
   500
Returns query object associated with current session object. Default query object class is L<CGI.pm|CGI>.
colas@0
   501
colas@0
   502
=head2 DEPRECATED METHODS
colas@0
   503
colas@0
   504
These methods exist solely for for compatibility with CGI::Session 3.x.
colas@0
   505
colas@0
   506
=head3 close()
colas@0
   507
colas@0
   508
Closes the session. Using flush() is recommended instead, since that's exactly what a call
colas@0
   509
to close() does now.
colas@0
   510
colas@0
   511
=head1 DISTRIBUTION
colas@0
   512
colas@0
   513
CGI::Session consists of several components such as L<drivers|"DRIVERS">, L<serializers|"SERIALIZERS"> and L<id generators|"ID GENERATORS">. This section lists what is available.
colas@0
   514
colas@0
   515
=head2 DRIVERS
colas@0
   516
colas@0
   517
Following drivers are included in the standard distribution:
colas@0
   518
colas@0
   519
=over 4
colas@0
   520
colas@0
   521
=item *
colas@0
   522
colas@0
   523
L<file|CGI::Session::Driver::file> - default driver for storing session data in plain files. Full name: B<CGI::Session::Driver::file>
colas@0
   524
colas@0
   525
=item *
colas@0
   526
colas@0
   527
L<db_file|CGI::Session::Driver::db_file> - for storing session data in BerkelyDB. Requires: L<DB_File>.
colas@0
   528
Full name: B<CGI::Session::Driver::db_file>
colas@0
   529
colas@0
   530
=item *
colas@0
   531
colas@0
   532
L<mysql|CGI::Session::Driver::mysql> - for storing session data in MySQL tables. Requires L<DBI|DBI> and L<DBD::mysql|DBD::mysql>.
colas@0
   533
Full name: B<CGI::Session::Driver::mysql>
colas@0
   534
colas@0
   535
=item *
colas@0
   536
colas@0
   537
L<sqlite|CGI::Session::Driver::sqlite> - for storing session data in SQLite. Requires L<DBI|DBI> and L<DBD::SQLite|DBD::SQLite>.
colas@0
   538
Full name: B<CGI::Session::Driver::sqlite>
colas@0
   539
colas@0
   540
=back
colas@0
   541
colas@0
   542
=head2 SERIALIZERS
colas@0
   543
colas@0
   544
=over 4
colas@0
   545
colas@0
   546
=item *
colas@0
   547
colas@0
   548
L<default|CGI::Session::Serialize::default> - default data serializer. Uses standard L<Data::Dumper|Data::Dumper>.
colas@0
   549
Full name: B<CGI::Session::Serialize::default>.
colas@0
   550
colas@0
   551
=item *
colas@0
   552
colas@0
   553
L<storable|CGI::Session::Serialize::storable> - serializes data using L<Storable>. Requires L<Storable>.
colas@0
   554
Full name: B<CGI::Session::Serialize::storable>.
colas@0
   555
colas@0
   556
=item *
colas@0
   557
colas@0
   558
L<freezethaw|CGI::Session::Serialize::freezethaw> - serializes data using L<FreezeThaw>. Requires L<FreezeThaw>.
colas@0
   559
Full name: B<CGI::Session::Serialize::freezethaw>
colas@0
   560
colas@0
   561
=item *
colas@0
   562
colas@0
   563
L<yaml|CGI::Session::Serialize::yaml> - serializes data using YAML. Requires L<YAML> or L<YAML::Syck>.
colas@0
   564
Full name: B<CGI::Session::Serialize::yaml>
colas@0
   565
colas@0
   566
=item *
colas@0
   567
colas@0
   568
L<json|CGI::Session::Serialize::json> - serializes data using JSON. Requires L<JSON::Syck>.
colas@0
   569
Full name: B<CGI::Session::Serialize::json>
colas@0
   570
colas@0
   571
=back
colas@0
   572
colas@0
   573
=head2 ID GENERATORS
colas@0
   574
colas@0
   575
Following ID generators are available:
colas@0
   576
colas@0
   577
=over 4
colas@0
   578
colas@0
   579
=item *
colas@0
   580
colas@0
   581
L<md5|CGI::Session::ID::md5> - generates 32 character long hexadecimal string. Requires L<Digest::MD5|Digest::MD5>.
colas@0
   582
Full name: B<CGI::Session::ID::md5>.
colas@0
   583
colas@0
   584
=item *
colas@0
   585
colas@0
   586
L<incr|CGI::Session::ID::incr> - generates incremental session ids.
colas@0
   587
colas@0
   588
=item *
colas@0
   589
colas@0
   590
L<static|CGI::Session::ID::static> - generates static session ids. B<CGI::Session::ID::static>
colas@0
   591
colas@0
   592
=back
colas@0
   593
colas@0
   594
colas@0
   595
=head1 CREDITS
colas@0
   596
colas@0
   597
CGI::Session evolved to what it is today with the help of following developers. The list doesn't follow any strict order, but somewhat chronological. Specifics can be found in F<Changes> file
colas@0
   598
colas@0
   599
=over 4
colas@0
   600
colas@0
   601
=item Andy Lester 
colas@0
   602
colas@0
   603
=item Brian King E<lt>mrbbking@@mac.comE<gt>
colas@0
   604
colas@0
   605
=item Olivier Dragon E<lt>dragon@@shadnet.shad.caE<gt>
colas@0
   606
colas@0
   607
=item Adam Jacob E<lt>adam@@sysadminsith.orgE<gt>
colas@0
   608
colas@0
   609
=item Igor Plisco E<lt>igor@@plisco.ruE<gt>
colas@0
   610
colas@0
   611
=item Mark Stosberg 
colas@0
   612
colas@0
   613
=item Matt LeBlanc E<lt>mleblanc@@cpan.orgE<gt>
colas@0
   614
colas@0
   615
=item Shawn Sorichetti
colas@0
   616
colas@0
   617
=back
colas@0
   618
colas@0
   619
=head1 COPYRIGHT
colas@0
   620
colas@0
   621
Copyright (C) 2001-2005 Sherzod Ruzmetov E<lt>sherzodr@@cpan.orgE<gt>. All rights reserved.
colas@0
   622
This library is free software. You can modify and or distribute it under the same terms as Perl itself.
colas@0
   623
colas@0
   624
=head1 PUBLIC CODE REPOSITORY
colas@0
   625
colas@0
   626
You can see what the developers have been up to since the last release by
colas@0
   627
checking out the code repository. You can browse the Subversion repository from here:
colas@0
   628
colas@0
   629
 http://svn.cromedome.net/
colas@0
   630
colas@0
   631
Or check it directly with C<svn> from here:
colas@0
   632
colas@0
   633
 svn://svn.cromedome.net/CGI-Session
colas@0
   634
colas@0
   635
=head1 SUPPORT
colas@0
   636
colas@0
   637
If you need help using CGI::Session consider the mailing list. You can ask the list by sending your questions to
colas@0
   638
cgi-session-user@@lists.sourceforge.net .
colas@0
   639
colas@0
   640
You can subscribe to the mailing list at https://lists.sourceforge.net/lists/listinfo/cgi-session-user .
colas@0
   641
colas@0
   642
Bug reports can be submitted at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Session
colas@0
   643
colas@0
   644
=head1 AUTHOR
colas@0
   645
colas@0
   646
Sherzod Ruzmetov E<lt>sherzodr@@cpan.orgE<gt>, http://author.handalak.com/
colas@0
   647
colas@0
   648
Mark Stosberg became a co-maintainer during the development of 4.0. C<markstos@@cpan.org>.
colas@0
   649
colas@0
   650
=head1 SEE ALSO
colas@0
   651
colas@0
   652
=over 4
colas@0
   653
colas@0
   654
=item *
colas@0
   655
colas@0
   656
L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual
colas@0
   657
colas@0
   658
=item *
colas@0
   659
colas@0
   660
B<RFC 2965> - "HTTP State Management Mechanism" found at ftp://ftp.isi.edu/in-notes/rfc2965.txt
colas@0
   661
colas@0
   662
=item *
colas@0
   663
colas@0
   664
L<CGI|CGI> - standard CGI library
colas@0
   665
colas@0
   666
=item *
colas@0
   667
colas@0
   668
L<Apache::Session|Apache::Session> - another fine alternative to CGI::Session
colas@0
   669
colas@0
   670
=back
colas@0
   671
colas@0
   672
@