NAME

OpenPlugin::Session - Save and retrieve session data

SYNOPSIS

 my $session = {}
 $session->{camel_humps}     = "one";
 $session->{fish_in_the_sea} = "lots";
 $session->{stooges}         = "three";

 my $session_id = $OP->session->save( $session );

 ...

 my $session = $OP->session->fetch( $session_id );
 print "Humps:   $session->{camel_humps}\n";       # Prints "one"
 print "Fish:    $session->{fish_in_the_sea}\n";   # Prints "lots"
 print "Stooges: $session->{stooges}\n";           # Prints "three"

DESCRIPTION

Sessions provide a means to save information across requests, for a given user. Typically, any values created or retrieved for a user are lost after the request. With sessions, one can store that data for later retrieval, as long as the user (or, more specifically, the browser) can later provide the unique key associated with the data.

METHODS

fetch( $session_id )

Given a session_id, retrieve an existing session.

Returns a hashref containing all the session data, or undef if the session has expired.

save( \%session_data, [ { id = $id, $expires => $date } ] )>

Save a session. If a session is already open, the existing session id is used. If a session id does not yet exist, a new one is created.

Returns the ID of the session saved, or undef on failure.

Basic parameters -- drivers may define others:

• session_data: Session data to save. This should be a reference to a hash.

• id (optional): Session ID to associate with the data being saved. If not specified, and you haven't called fetch yet this session, an id will be randomly chosen for you. If you have called fetch, the same ID used to fetch the session will be used to save it. Usually, you don't need to pass this in.

• expires (optional): Expiration time, in the format:

   "now"  - expire immediately
   "+180s - in 180 seconds
   "+2m"  - in 2 minutes
   "+12h" - in 12 hours
   "+1d"  - in 1 day
   "+3M"  - in 3 months
   "+2y"  - in 2 years
   "-3m"  - 3 minutes ago(!)

  If not specified, the item will have the same expiration time as is listed in the config file.

session_id()

Returns session ID for the current session. If the session is new or not yet saved this will return undef.

create()

Create a new session. It is not necessary to call this function to use sessions -- fetch and save do the same thing. This function can be used when you wish to create a session and get your session id, but aren't ready to save anything yet.

Returns the ID of the session created.

delete( [ $session_id ] )

Delete an existing session. If no parameters are passed, it defaults to deleting the last session opened. You may pass in a session_id to explicitly delete a particular session.

Returns the ID of the session deleted if successful.

BUGS

None known.

TO DO

The interface for this module is not complete. Methods for accessing the sessions creation, modified, and accessed time should be created. Also one for finding when it will expire.

I'm also pondering the creation of an OO interface for this module, much like CGI::Session. Instead of passing a hashref to the save() function, you'd use some sort of param() method to save each piece of data. Maybe.

SEE ALSO

OpenPlugin

Apache::Session

CGI::Session

COPYRIGHT

Copyright (c) 2001-2003 Eric Andreychek. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Eric Andreychek <eric@openthought.net>

cpanm OpenPlugin

perl -MCPAN -e shell
install OpenPlugin