Line: 11 to 11 | ||||||||
---|---|---|---|---|---|---|---|---|
# Object initialization: use CGI::Session; | ||||||||
Changed: | ||||||||
< < | $session = new CGI::Session(); | |||||||
> > | $session = CGI::Session->new(); | |||||||
$CGISESSID = $session->id(); | ||||||||
Changed: | ||||||||
< < | # send proper HTTP header with cookies: | |||||||
> > | # Send proper HTTP header with cookies: | |||||||
print $session->header(); | ||||||||
Changed: | ||||||||
< < | # storing data in the session | |||||||
> > | # Storing data in the session: | |||||||
$session->param('f_name', 'Sherzod'); # or $session->param(-name=>'l_name', -value=>'Ruzmetov'); | ||||||||
Changed: | ||||||||
< < | # flush the data from memory to the storage driver at least before your # program finishes since auto-flushing can be unreliable | |||||||
> > | # Flush the data from memory to the storage driver at least before your # program finishes since auto-flushing can be unreliable. | |||||||
$session->flush(); | ||||||||
Changed: | ||||||||
< < | # retrieving data | |||||||
> > | # Retrieving data: | |||||||
my $f_name = $session->param('f_name'); # or my $l_name = $session->param(-name=>'l_name'); | ||||||||
Changed: | ||||||||
< < | # clearing a certain session parameter | |||||||
> > | # Clearing a certain session parameter: | |||||||
$session->clear(["l_name", "f_name"]); | ||||||||
Changed: | ||||||||
< < | # expire '_is_logged_in' flag after 10 idle minutes: | |||||||
> > | # Expire '_is_logged_in' flag after 10 idle minutes: | |||||||
$session->expire('is_logged_in', '+10m') | ||||||||
Changed: | ||||||||
< < | # expire the session itself after 1 idle hour | |||||||
> > | # Expire the session itself after 1 idle hour: | |||||||
$session->expire('+1h'); | ||||||||
Changed: | ||||||||
< < | # delete the session for good | |||||||
> > | # Delete the session for good: | |||||||
$session->delete(); | ||||||||
Added: | ||||||||
> > | $session->flush(); # Recommended practice says use flush() after delete(). | |||||||
=head1 DESCRIPTION | ||||||||
Changed: | ||||||||
< < | CGI-Session is a Perl5 library that provides an easy, reliable and modular session management system across HTTP requests.
Persistency is a key feature for such applications as shopping carts, login/authentication routines, and application that
need to carry data across HTTP requests. CGI::Session does that and many more.
=head1 TRANSLATIONS
This document is also available in Japanese.
=over 4
=item o
Translation based on 4.14: http://digit.que.ne.jp/work/index.cgi?Perldoc/ja
=item o
Translation based on 3.11, including Cookbook and Tutorial: http://perldoc.jp/docs/modules/CGI-Session-3.11/
=back
=head1 TO LEARN MORE
Current manual is optimized to be used as a quick reference. To learn more both about the philosophy and CGI::Session
programming style, consider the following:
=over 4
=item *
L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual. Also includes library architecture and driver specifications.
=item *
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
=item *
B | |||||||
> > | CGI::Session provides an easy, reliable and modular session management system across HTTP requests. | |||||||
=head1 METHODS | ||||||||
Line: 109 to 63 | ||||||||
=head2 new( $dsn, $query||$sid, \%dsn_args ) | ||||||||
Changed: | ||||||||
< < | 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">. | |||||||
> > | =head2 new( $dsn, $query||$sid, \%dsn_args, \%session_params ) 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()">. | |||||||
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. | ||||||||
Line: 125 to 81 | ||||||||
$s = CGI::Session->new("serializer:storable;id:incr", $sid); # etc... | ||||||||
Added: | ||||||||
> > | Briefly, C<new()> will return an initialized session object with a valid id, whereas C<load()> may return an empty session object with an undefined id. Tests are provided (t/new_with_undef.t and t/load_with_undef.t) to clarify the result of calling C<new()> and C<load()> with undef, or with an initialized CGI object with an undefined or fake CGISESSID. You are strongly advised to run the old-fashioned 'make test TEST_FILES=t/new_with_undef.t TEST_VERBOSE=1' or the new-fangled 'prove -v t/new_with_undef.t', for both new*.t and load*.t, and examine the output. | |||||||
Following data source components are supported: | ||||||||
Line: 147 to 111 | ||||||||
For example, to get CGI::Session store its data using DB_File and serialize data using FreezeThaw: | ||||||||
Changed: | ||||||||
< < | $s = new CGI::Session("driver:DB_File;serializer:FreezeThaw", undef); | |||||||
> > | $s = CGI::Session->new("driver:DB_File;serializer:FreezeThaw", undef); | |||||||
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. | ||||||||
Added: | ||||||||
> > | If called with four arguments, the first three match previous examples. The fourth argument must be a hash reference with parameters to be used by the CGI::Session object. (see \%session_params above )
The following is a list of the current keys:
=over
=item *
B | |||||||
undef is acceptable as a valid placeholder to any of the above arguments, which will force default behavior. =head2 load() | ||||||||
Line: 159 to 135 | ||||||||
=head2 load($dsn, $query||$sid) | ||||||||
Changed: | ||||||||
< < | =head2 load($dsn, $query, \%dsn_args); | |||||||
> > | =head2 load( $dsn, $query, \%dsn_args ) =head2 load( $dsn, $query, \%dsn_args, \%session_params ) | |||||||
Accepts the same arguments as new(), and also returns a new session object, or | ||||||||
Changed: | ||||||||
< < | undef on failure. The difference is, L<new()|/"new"> can create new session if | |||||||
> > | undef on failure. The difference is, L<new()|/"new()"> can create a new session if | |||||||
it detects expired and non-existing sessions, but C<load()> does not. 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: | ||||||||
Line: 180 to 158 | ||||||||
$s = $s->new() or die $s->errstr; } | ||||||||
Changed: | ||||||||
< < | Notice, all I | |||||||
> > | Notice: All I | |||||||
=head2 id() | ||||||||
Line: 207 to 194 | ||||||||
=head2 param_hashref() | ||||||||
Changed: | ||||||||
< < | B | |||||||
> > | B | |||||||
=head2 dataref() | ||||||||
Line: 226 to 213 | ||||||||
=head2 save_param($query, \@list) | ||||||||
Changed: | ||||||||
< < | 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. | |||||||
> > | Saves query parameters to session object. In other words, it's the same as calling L<param($name, $value)|/"param($name)"> 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. | |||||||
=head2 load_param() | ||||||||
Line: 251 to 238 | ||||||||
Synchronizes data in memory with the copy serialized by the driver. Call flush() if you need to access the session from outside the current session object. You should | ||||||||
Changed: | ||||||||
< < | at least call flush() before your program exits. | |||||||
> > | call flush() sometime before your program exits. | |||||||
As a last resort, CGI::Session will automatically call flush for you just | ||||||||
Changed: | ||||||||
< < | before the program terminates or session object goes out of scope. This automatic behavior was the recommended behavior until the 4.x series. Automatic flushing has since proven to be unreliable, and in some cases is now required in places that worked with 3.x. For further details see: | |||||||
> > | before the program terminates or session object goes out of scope. Automatic flushing has proven to be unreliable, and in some cases is now required in places that worked with CGI::Session 3.x. Always explicitly calling C<flush()> on the session before the program exits is recommended. For extra safety, call it immediately after every important session update. | |||||||
Changed: | ||||||||
< < | http://rt.cpan.org/Ticket/Display.html?id=17541 http://rt.cpan.org/Ticket/Display.html?id=17299 | |||||||
> > | Also see L | |||||||
=head2 atime() | ||||||||
Line: 277 to 266 | ||||||||
=head2 expire($param, $time) | ||||||||
Changed: | ||||||||
< < | Sets expiration interval relative to L<atime()|/"atime">. | |||||||
> > | Sets expiration interval relative to L<atime()|/"atime()">. | |||||||
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. | ||||||||
Line: 343 to 332 | ||||||||
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. | ||||||||
Added: | ||||||||
> > | =head2 ip_match() Returns true if $ENV{REMOTE_ADDR} matches the remote address stored in the session. If you have an application where you are sure your users' IPs are constant during a session, you can consider enabling an option to make this check: use CGI::Session '-ip_match'; Usually you don't call ip_match() directly, but by using the above method. It is useful only if you want to call it inside of coderef passed to the L<find()|/"find( \&code )"> method. | |||||||
=head2 delete() | ||||||||
Changed: | ||||||||
< < | 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 | |||||||
> > | Sets the objects status to be "deleted". Subsequent read/write requests on the same object will fail. To physically delete it from the data store you need to call L<flush()|/"flush()">. CGI::Session attempts to do this automatically when the object is being destroyed (usually as the script exits), but see L. | |||||||
=head2 find( \&code ) | ||||||||
Line: 359 to 363 | ||||||||
CGI::Session->find( sub {} ); | ||||||||
Changed: | ||||||||
< < | 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: | |||||||
> > | Notice, above \&code didn't have to do anything, because load(), which is called to initialize sessions inside L<find()|/"find( \&code )">, will automatically remove expired sessions. Following example will remove all the objects that are 10+ days old: | |||||||
CGI::Session->find( \&purge ); sub purge { my ($session) = @_; next if $session->is_empty; # <-- already expired?! if ( ($session->ctime + 3600*240) <= time() ) { | ||||||||
Changed: | ||||||||
< < | $session->delete() or warn "couldn't remove " . $session->id . ": " . $session->errstr; | |||||||
> > | $session->delete(); $session->flush(); # Recommended practice says use flush() after delete(). | |||||||
} } | ||||||||
Line: 439 to 444 | ||||||||
B<Note:> find() is meant to be convenient, not necessarily efficient. It's best suited in cron scripts. | ||||||||
Added: | ||||||||
> > | =head2 name($new_name)
The $new_name parameter is optional. If supplied it sets the query or cookie parameter name to be used.
It defaults to I<$CGI::Session::NAME>, which defaults to I | |||||||
=head1 MISCELLANEOUS METHODS =head2 remote_addr() | ||||||||
Line: 456 to 472 | ||||||||
=head2 header() | ||||||||
Changed: | ||||||||
< < | 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: | |||||||
> > | A wrapper for C | |||||||
$cookie = CGI::Cookie->new(-name=>$session->name, -value=>$session->id); | ||||||||
Changed: | ||||||||
< < | print $cgi->header(-cookie=>$cookie); | |||||||
> > | print $cgi->header(-cookie=>$cookie, @_); | |||||||
You can minimize the above into: print $session->header(); | ||||||||
Changed: | ||||||||
< < | 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: | |||||||
> > | 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 this before creating session object: | |||||||
CGI::Session->name("MY_SID"); | ||||||||
Changed: | ||||||||
< < | $session = new CGI::Session(undef, $cgi, \%attrs); | |||||||
> > | $session = CGI::Session->new(undef, $cgi, \%attrs); | |||||||
Changed: | ||||||||
< < | Now, $session->header() uses "MY_SID" as a name for the session cookie. | |||||||
> > | Now, $session->header() uses "MY_SID" as the name for the session cookie. For all additional options that can
be passed, see the C<header()> docs in C | |||||||
=head2 query() | ||||||||
Changed: | ||||||||
< < | Returns query object associated with current session object. Default query object class is L<CGI.pm|CGI>. | |||||||
> > | Returns query object associated with current session object. Default query object class is C | |||||||
=head2 DEPRECATED METHODS | ||||||||
Line: 491 to 509 | ||||||||
=head2 DRIVERS | ||||||||
Changed: | ||||||||
< < | Following drivers are included in the standard distribution: | |||||||
> > | The following drivers are included in the standard distribution: | |||||||
=over 4 | ||||||||
Line: 516 to 534 | ||||||||
=back | ||||||||
Added: | ||||||||
> > | Other drivers are available from CPAN. | |||||||
=head2 SERIALIZERS =over 4 | ||||||||
Line: 540 to 560 | ||||||||
L<yaml|CGI::Session::Serialize::yaml> - serializes data using YAML. Requires L | ||||||||
Deleted: | ||||||||
< < | =item * L<json|CGI::Session::Serialize::json> - serializes data using JSON. Requires L<JSON::Syck>. Full name: B<CGI::Session::Serialize::json> | |||||||
=back =head2 ID GENERATORS | ||||||||
Changed: | ||||||||
< < | Following ID generators are available: | |||||||
> > | The following ID generators are included in the standard distribution. | |||||||
=over 4 | ||||||||
Line: 568 to 583 | ||||||||
=back | ||||||||
Added: | ||||||||
> > | =head1 A Warning about Auto-flushing
Auto-flushing can be unreliable for the following reasons. Explicit flushing
after key session updates is recommended.
=over 4
=item If the C | |||||||
=head1 CREDITS | ||||||||
Line: 591 to 705 | ||||||||
=item Shawn Sorichetti | ||||||||
Added: | ||||||||
> > | =item Ron Savage =item Rhesa Rozendaal He suggested Devel::Cycle to help debugging. | |||||||
=back | ||||||||
Added: | ||||||||
> > | Also, many people on the CGI::Application and CGI::Session mailing lists have contributed ideas and suggestions, and battled publicly with bugs, all of which has helped. | |||||||
=head1 COPYRIGHT
Copyright (C) 2001-2005 Sherzod Ruzmetov E | ||||||||
Line: 601 to 724 | ||||||||
=head1 PUBLIC CODE REPOSITORY You can see what the developers have been up to since the last release by | ||||||||
Changed: | ||||||||
< < | checking out the code repository. You can browse the Subversion repository from here: | |||||||
> > | checking out the code repository. You can browse the git repository from here: | |||||||
Changed: | ||||||||
< < | http://svn.cromedome.net/ | |||||||
> > | http://github.com/cromedome/cgi-session/tree/master | |||||||
Changed: | ||||||||
< < | Or check it directly with C | |||||||
> > | Or check out the code with: | |||||||
Changed: | ||||||||
< < | svn://svn.cromedome.net/CGI-Session | |||||||
> > | git clone git://github.com/cromedome/cgi-session.git | |||||||
=head1 SUPPORT | ||||||||
Changed: | ||||||||
< < | If you need help using CGI::Session consider the mailing list. You can ask the list by sending your questions to cgi-session-user@lists.sourceforge.net . | |||||||
> > | If you need help using CGI::Session, ask on the mailing list. You can ask the list by sending your questions to cgi-session-user@lists.sourceforge.net . | |||||||
You can subscribe to the mailing list at https://lists.sourceforge.net/lists/listinfo/cgi-session-user . | ||||||||
Line: 620 to 743 | ||||||||
=head1 AUTHOR | ||||||||
Changed: | ||||||||
< < | Sherzod Ruzmetov E | |||||||
> > | Sherzod Ruzmetov C<sherzodr@cpan.org> | |||||||
Mark Stosberg became a co-maintainer during the development of 4.0. C<markstos@cpan.org>. | ||||||||
Added: | ||||||||
> > | Ron Savage became a co-maintainer during the development of 4.30. C<rsavage@cpan.org>. If you would like support, ask on the mailing list as describe above. The maintainers and other users are subscribed to it. | |||||||
=head1 SEE ALSO | ||||||||
Added: | ||||||||
> > | To learn more both about the philosophy and CGI::Session programming style, consider the following: | |||||||
=over 4 =item * | ||||||||
Changed: | ||||||||
< < | L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual | |||||||
> > | L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual. Also includes library architecture and driver specifications. | |||||||
=item * | ||||||||
Changed: | ||||||||
< < | B | |||||||
> > | 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 | |||||||
Changed: | ||||||||
< < | L<CGI|CGI> - standard CGI library | |||||||
> > | =item * B | |||||||
=item * | ||||||||
Changed: | ||||||||
< < | L<Apache::Session|Apache::Session> - another fine alternative to CGI::Session | |||||||
> > | L<Apache::Session|Apache::Session> - an alternative to CGI::Session. | |||||||
=back |
Line: 1 to 1 | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Added: | |||||||||||||||||
> > | Package ==extends CGI::Session::ErrorHandler =head1 NAME CGI::Session - persistent session data in CGI applications =head1 SYNOPSIS # Object initialization: use CGI::Session; $session = new CGI::Session(); $CGISESSID = $session->id(); # send proper HTTP header with cookies: print $session->header(); # storing data in the session $session->param('f_name', 'Sherzod'); # or $session->param(-name=>'l_name', -value=>'Ruzmetov'); # flush the data from memory to the storage driver at least before your # program finishes since auto-flushing can be unreliable $session->flush(); # retrieving data my $f_name = $session->param('f_name'); # or my $l_name = $session->param(-name=>'l_name'); # clearing a certain session parameter $session->clear(["l_name", "f_name"]); # expire '_is_logged_in' flag after 10 idle minutes: $session->expire('is_logged_in', '+10m') # expire the session itself after 1 idle hour $session->expire('+1h'); # delete the session for good $session->delete(); =head1 DESCRIPTION CGI-Session is a Perl5 library that provides an easy, reliable and modular session management system across HTTP requests. Persistency is a key feature for such applications as shopping carts, login/authentication routines, and application that need to carry data across HTTP requests. CGI::Session does that and many more. =head1 TRANSLATIONS This document is also available in Japanese. =over 4 =item o Translation based on 4.14: http://digit.que.ne.jp/work/index.cgi?Perldoc/ja =item o Translation based on 3.11, including Cookbook and Tutorial: http://perldoc.jp/docs/modules/CGI-Session-3.11/ =back =head1 TO LEARN MORE Current manual is optimized to be used as a quick reference. To learn more both about the philosophy and CGI::Session programming style, consider the following: =over 4 =item * L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual. Also includes library architecture and driver specifications. =item * 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 =item * B
|