++ed by:
ARPI

1 PAUSE user
1 non-PAUSE user.

Gligan Calin Horea
and 1 contributors

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.12

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 fail

    Example :

        #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" } );

triggers

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

Example :

    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 { ... },
                                        }
                            );

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;

run_trigger

Runs a trigger for the given field

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::Session

You can also look for information at:

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.