NAME
WWW::Session - Generic session management engine for web applications
DESCRIPTION
Generic session management engine for web applications with multiple backends, object serialization and data validation
VERSION
Version 0.09
SYNOPSIS
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
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() },
}
};
SESSION & OBJECTS
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);
STORAGE BACKENDS
You can use one or more of the fallowing backends (the list might not be complete, more backends might be available on CPAN):
File storage
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
Database storage
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
Memcached storage
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
SUBROUTINES/METHODS
new
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});find
Retieves the session object for the given session id
Usage :
my $session = WWW::Session->find('session_id');find_or_create
Retieves the session object for the given session id if it exists, if not it creates a new object with the given session id
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),
Usage:
my $session = WWW::Session->find_or_create('session_id',{ c=>2 })set
Adds/sets a new value for the given field
Usage :
$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);get
Retrieves the value of the given key from the session object
Usage :
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();delete
Removes the given key from the session data
Usage :
$session->delete('user');sid
Returns the session id associated with this session
expires
Getter/Setter for the expiration time of this session
add_storage
Adds a new storge engine to the list of Storage engines that will be used to store the session info
Usage :
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
serialization_engine
Configures the serialization engine to be used for serialising sessions.
The default serialization engine is JSON
Usage :
WWW::Session->serialization_engine('JSON');Parameters :
$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
autosave
Turn on/off the autosave feature (on by default)
If this feature is on the object will always be saved before beying destroyed
Usage :
WWW::Session->autosave(1);default_expiration_time
Setter/Getter for the default expiration time
Usage :
WWW::Session->default_expiration_time(1800);destroy
Completely removes all the data related to the current session
NOTE: After calling destroy the session object will no longer be usable
Usage :
$session->destroy();setup_field
Sets up the filters, inflators and deflators for the given field
deflators
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.
Example :
# 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
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.
Example :
# 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
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 failExample :
#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
Example :
#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"
Example :
#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" } );
Note: The entire setup for a field must be done in a single call to setup_field() or the previous settings will be overwritten!
Example :
WWW::Session->setup_field(
'user',
filter => { isa => "MyApp::User" },
deflate => sub { $_[0]->id() },
inflate => sub { return MyApp::User->find($_[0]) }
);save
Serializes a WWW::Session object sends it to all storage engines for saving
ACCESSING SESSION DATA
Allows us to get/set session data directly by calling the field name as a method
Example:
my $user = $session->user(); #same as $user = $session->get('user');
#or
$session->age(21); #same as $session->set('age',21);AUTOSAVE FEATURE
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.
Example :
#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 :
- 1 Make a change that can be detected
-
$session->some_random_field( time() ); - 2 Save the session manually
-
$session->save();
PRIVATE METHODS
load
Deserializes a WWW::Session object from the given string and deflates all the fields that were inflated when the session was serialized
import
Allows us to configure all the module options in one line
Example :
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;TIE INTERFACE
The WWW::Session objects can be tied to hashes to make them easier to use
Example :
my %session;
tie %session, WWW::Session, 'session_id', {user => $user, authenticated => 1};
...
my $user = $session{user};
...
$session{authenticated} = 0;
delete $session{user};AUTHOR
Gligan Calin Horea, <gliganh at gmail.com>
BUGS
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.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WWW::SessionYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
LICENSE AND COPYRIGHT
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.