WWW::Session - Generic session management engine for web applications
Generic session management engine for web applications with multiple backends, object serialization and data validation
Version 0.12
This module allows you to easily create sessions , store data in them and later retrieve that information, using multiple storage backends
Example:
use WWW::Session; #set up the storage backends WWW::Session->add_storage( 'File', {path => '/tmp/sessions'} ); WWW::Session->add_storage( 'Memcached', {servers => ['127.0.0.1:11211']} ); #Set up the serialization engine (defaults to JSON) WWW::Session->serialization_engine('JSON'); #Set up the default expiration time (in seconds or -1 for never) WWW::Session->default_expiration_time(3600); #Turn on autosave WWW::Session->autosave(1); #and than ... #Create a new session my $session = WWW::Session->new($sid,$hash_ref); ... $session->sid(); #returns $sid $session->data(); #returns $hash_ref #set the user $session->user($user); #retrieve the user my $user = $session->user(); #returns undef if it doesn't exist or it's expired my $session = WWW::Session->find($sid); #returns the existing session if it exists, creates a new session if it doesn't my $session = WWW::Session->find_or_create($sid);
Using the session :
Settings values
There are two ways you can save a value on the session :
$session->set('user',$user); or $session->user($user);
If the requested field ("user" in the example above) already exists it will be assigned the new value, if it doesn't it will be added.
When you set a value for a field it will be validated first (see setup_field() ). If the value doesn't pass validation the field will keep it's old value and the set method will return 0. If everything goes well the set method will return 1.
Retrieving values
my $user = $session->get('user'); or my $user = $session->user();
If the requested field ("user" in the example above) already exists it will return it's value, otherwise will return undef
undef
We can automaticaly deflate/inflate certain informations when we store / retrieve from storage the session data (see setup_field() for more details):
WWW::Session->setup_field( 'user', inflate => sub { return Some::Package->new( $_[0] ) }, deflate => sub { $_[0]->id() } );
We can automaticaly validate certain informations when we store / retrieve from storage the session data (see setup_field() for more details):
WWW::Session->setup_field( 'age', filter => sub { $_[0] >= 18 } );
Another way to initialize the module :
use WWW::Session storage => [ 'File' => { path => '/tmp/sessions'}, 'Memcached' => { servers => ['127.0.0.1'] } ], serialization => 'JSON', expires => 3600, fields => { user => { inflate => sub { return Some::Package->new( $_[0] ) }, deflate => sub { $_[0]->id() }, } };
The default serialization engine is JSON, but JSON can't serialize objects by default, you will have to write more code to accomplish that. If your session data data contains objects you can take one of the following approaches :
Use inflate/deflate (recommended)
# if we have a user object (eg MyApp::User) we can deflate it like this WWW::Session->setup_field('user', deflate => sub { return $_[0]->id() } ); #and inflate it back like this WWW::Session->setup_field('user',inflate => sub { return Some::Package->new( $_[0] ) } );
This method even thow it's slower, it reduces the size of the session object when stored, and it ensures that if the object data changed since we saved it, this changes will be reflected in the object when we retrieve restore it (usefull for database result objects)
Change the serialization module to 'Storable'
The 'Storable' serialization engine can handle object without any additional changes
WWW::Session->serialization_engine('Storable');
Note : The perl Storable module is not very compatible between different version, so sharing data between multiple machines could cause problems. We recommad using the 'JSON' engine with inflate/defate (described above);
You can use one or more of the fallowing backends (the list might not be complete, more backends might be available on CPAN):
Here is how you can set up the File storage backend :
use WWW::Session; WWW::Session->add_storage('File', {path => '.'} );
See WWW::Session::Storage::File for more details
If you want to store your session is MySQL do this :
use WWW::Session; WWW::Session->add_storage( 'MySQL', { dbh => $dbh, table => 'sessions', fields => { sid => 'session_id', expires => 'expires', data => 'data' }, } );
The "fields" hasref contains the mapping of session internal data to the column names from MySQL. The keys are the session fields ("sid","expires" and "data") and must all be present.
The MySQL types of the columns should be :
sid => varchar(32)
expires => DATETIME or TIMESTAMP
data => text
See WWW::Session::Storage::MySQL for more details
To use memcached as a storage backend do this : use WWW::Session; WWW::Session->add_storage('Memcached', {servers => ['127.0.0.1:11211']} );
See WWW::Session::Storage::Memcached for more details
Creates a new session object with the unique identifier and the given data. If a session with the same identifier previously existed it will be overwritten
Parameters
sid = unique id for this session
data = hash reference containing the data that we want to store in the session object
exipres = for how many secconds is this session valid (defaults to the default expiration time)
Retuns a WWW::Session object
Usage :
my $session = WWW::Session->new('session_id',{ a=> 1, b=> 2});
Retieves the session object for the given session id
my $session = WWW::Session->find('session_id');
Retieves the session object for the given session id if it exists, if not it creates a new object with the given session id
exipres = for how many secconds is this session valid (defaults to the default expiration time),
Usage:
my $session = WWW::Session->find_or_create('session_id',{ c=>2 })
Adds/sets a new value for the given field
$session->set('user',$user);
The values can also be set by calling the name of the field you want to set as a method :
$session->user($user);
Retrieves the value of the given key from the session object
my $user = $session->get('user');
You can also use the name of the field you want to retrieve as a method. The above call does the same as :
my $user = $session->user();
Removes the given key from the session data
$session->delete('user');
Returns the session id associated with this session
Getter/Setter for the expiration time of this session
Adds a new storge engine to the list of Storage engines that will be used to store the session info
WWW::Session->add_storage($storage_engine_name,$storage_engine_options);
Parameters :
$storage_engine_name = Name of the class that defines a valid storage engine
For WWW::Session::Storage::* modules you can use only the name of the storage, you don't need the full name. eg Memcached and WWW::Session::Storage::Memcached are synonyms
$storage_engine_options = hash ref containing the options that will be passed on to the storage engine module when new() is called
Example :
WWW::Session->add_storage( 'File', {path => '/tmp/sessions'} ); WWW::Session->add_storage( 'Memcached', {servers => ['127.0.0.1:11211']} );
See each storage module for aditional details
Configures the serialization engine to be used for serialising sessions.
The default serialization engine is JSON
WWW::Session->serialization_engine('JSON');
$serialization_engine_name = Name of the class that defines a valid serialization engine
For WWW::Session::Serialization::* modules you can use only the short name of the module, you don't need the full name. eg JSON and WWW::Session::Serialization::JSON are synonyms
Turn on/off the autosave feature (on by default)
If this feature is on the object will always be saved before beying destroyed
WWW::Session->autosave(1);
Setter/Getter for the default expiration time
WWW::Session->default_expiration_time(1800);
Completely removes all the data related to the current session
NOTE: After calling destroy the session object will no longer be usable
$session->destroy();
Sets up the filters, inflators and deflators for the given field
Deflators are passed as code refs. The only argument the deflator method receives is the value of the filed that it must be deflated and it must return a single value (scalar, object or reference) that will be asigned to the key.
# if we have a user object (eg MyApp::User) we can deflate it like this WWW::Session->setup_field('user', deflate => sub { return $_[0]->id() } );
Inflators are passed as code refs. The only argument the inflator method receives is the value of the filed that it must inflate and it must return a single value (scalar, object or reference) that will be asigned to the key.
# if we have a user object (eg MyApp::User) we can inflate it like this WWW::Session->setup_field('user',inflate => sub { return Some::Package->new( $_[0] ) } );
Filters can be used to ensure that the values from the session have the required values
Filters can be :
array ref
In this case when we call $session->set($field,$value) the values will have to be one of the values from the array ref , or the operation will fail
#Check that the age is between 18 and 99 WWW::Session->setup_field('age',filter => [18..99] );
code ref
In this case the field value will be passed to the code ref as the only parameter. The code ref must return a true or false value. If it returns a false value the set() operation will fail
#Check that the age is > 18 WWW::Session->setup_field('age',filter => sub { $_[0] > 18 } );
hash ref
In this case the only key from the hash that is recognised is "isa" will will chek that the given value has the types specified as the value for "isa"
#Check that the 'rights' field is an array WWW::Session->setup_field('age',filter => { isa => "ARRAY" } ); #Check that the 'user' field is an MyApp::User object WWW::Session->setup_field('user',filter => { isa => "MyApp::User" } );
Triggers allow you to execute a code ref when certain events happen on the key.
The return values from the triggers are completely ignored.
Available triggers are:
before_set_value
Executed before the value is actually storred on the code. Arguments sent to the code ref are : session object , new value, old value - in this order
after_set_value
Executed after the new value is set on the session object. Arguments sent to the code ref are : session object, new value
before_delete
Executed before the key is removed from the session object. Arguments sent to the code ref are : session object, current_value
after_delete
Executed after the key is removed from the session object. Arguments sent to the code ref are : session object, previous_value
WWW::Session->setup_field( 'user', filter => { isa => "MyApp::User" }, deflate => sub { $_[0]->id() }, inflate => sub { return MyApp::User->find($_[0]) } trigger => { before_set_value => sub { warn "About to set the user }, after_delete => sub { ... }, } );
Serializes a WWW::Session object sends it to all storage engines for saving
Allows us to get/set session data directly by calling the field name as a method
my $user = $session->user(); #same as $user = $session->get('user'); #or $session->age(21); #same as $session->set('age',21);
If you set autosave to 1 the session will be saved before the object is destroyed if any data has changed
BE CAREFULL : If you store complex structures only the changes made to direct session keys will be detected.
#this change will be detected because it affects a direct session attribute $session->age(21); #this changes won't be detected : my $user = $session->user(); $user->{age} = 21;
You have two choices :
$session->some_random_field( time() );
$session->save();
Deserializes a WWW::Session object from the given string and deflates all the fields that were inflated when the session was serialized
Allows us to configure all the module options in one line
use WWW::Session storage => [ 'File' => { path => '/tmp/sessions'}, 'Memcached' => { servers => ['127.0.0.1'] } ], serialization => 'Storable', expires => 3600, fields => { user => { inflate => sub { return Some::Package->new( $_[0]->id() ) }, deflate => sub { $_[0]->id() }, }, age => { filter => [21..99], } }, autosave => 1;
Runs a trigger for the given field
The WWW::Session objects can be tied to hashes to make them easier to use
my %session; tie %session, WWW::Session, 'session_id', {user => $user, authenticated => 1}; ... my $user = $session{user}; ... $session{authenticated} = 0; delete $session{user};
Gligan Calin Horea, <gliganh at gmail.com>
<gliganh at gmail.com>
Please report any bugs or feature requests to bug-www-session at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Session. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-www-session at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc WWW::Session
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Session
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/WWW-Session
CPAN Ratings
http://cpanratings.perl.org/d/WWW-Session
Search CPAN
http://search.cpan.org/dist/WWW-Session/
Copyright 2012 Gligan Calin Horea.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install WWW::Session, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Session
CPAN shell
perl -MCPAN -e shell install WWW::Session
For more information on module installation, please visit the detailed CPAN module installation guide.