expire($time) calls validate_time($time) to perform the conversion from '2h' to seconds, so "validate_time($time)" is available to you too.

If setting a time like this, expire($time) returns 1.

Note: The time set here is passed as the 3rd parameter to the storage driver's store() method (for all types of storage), and from there as the 3rd parameter to the set() method of Cache::Memcached. Of course, this doesn't happen immediately - it only happens when the session is saved.

o $session -> expire($key_1 => $time_1[, $key_2 => $time_2...])

Use $session -> expire($key_1 => $time_1[, $key_2 => $time_2...]) to set the expiry times of session parameters.

load_param([$q][, $name])

$q is a query object, and $name is a parameter name or an arrayref of names.

If the query object is not specified, generates one by calling $session -> load_query_class, and stores it in the internal 'query' attribute.

If you don't provide $q, use undef, don't just omit the parameter.

If $name is specified, only the session parameters named in the arrayref are processed.

If $name is not specified, copies all parameters belonging to the query object.

load_query_class()

Returns the query object.

This calls $session -> query_class -> new if the session object's query object is not defined.

load_session()

Returns a session.

Note: This method does not take any parameters, and hence does not function in the same way as load(...) in CGI::Session.

Algorithm:

o If user_id() returns a session id, try to load that session

If that succeeds, return the session.

If it fails, generate a new session, and return it.

You can call is_new() to tell the difference between these 2 cases.

o If user_id() returns 0, generate a new session, and return it

modified()

Returns a Boolean (0/1) indicating whether or not the session's parameters have been modified.

However, changing a value from one form of not-defined, e.g. undef, to another form of not-defined, e.g. 0, is ignored, meaning the modified flag is not set. In such cases, you could set the flag youself.

Note: Loading a session from storage changes the session's last access time, which means the session has been modified.

If you wish to stop the session being written to storage, without deleting it, you can reset the modified flag with $session -> modified(0).

param([@arg])

The [] indicates an optional parameter.

Specifies that you wish to retrieve data stored in the session, or you wish to store data in the session.

Data is stored in the session object as in a hash, via a set of $key => $value relationships.

The first example in the Synopsis shows a very simple CGI script doing the right thing by calling flush() just before it exits.

Alternately, if you sub-class CGI::Snapp, the call to flush() is best placed in your teardown() method, which is where you override "teardown()" in CGI::Snapp. The point here is that your teardown() is called automatically at the end of each run mode.

But why? Because the part 'param(my_hash => %my_hash)' is basically assigning a list (%my_hash) to a scalar (my_hash). Hence, only 1 element of the list (the 'first' key in some unknown order) will be assigned.

So, when you try to restore the hash with 'my(%my_hash) ...', all you'll get back is a scalar, which will generate the classic error message 'Odd number of elements in hash assignment...'.

I decided to circumvent it by using DBIx::Admin::DSNManager and adopting the wonders of nested testing. But, since V 1.11, I've replaced that module with Config::Tiny, to reduce dependencies, and hence to make it easier to get Data::Session into Debian.

Trouble with Exiting

If the session object's clean-up code is called, in DESTROY(), the session data is automatically flushed to storage (except when it's been deleted, or has not been modified).

However, as explained below, there can be problems with your code (i.e. not with Data::Session) such that this clean-up code is not called, or, if called, it cannot perform as expected.

The general guideline, then, is that you should explicitly call flush() on the session object before your program exits.

Common traps for beginners:

o Creating 2 CGI-like objects

If your code creates an object of type CGI or similar, but you don't pass that object into Data::Session via the 'query' parameter to new(), this module will create one for you, which can be very confusing.

The solution is to always create such a object yourself, and to always pass that into Data::Session.

In the case that the user of a CGI script runs your code for the first time, there will be no session id, either from a cookie or from a form field.

In such a case, Data::Session will do what you expect, which is to generate a session id.

o Letting your database handle go out of scope too early

When your script is exiting, and you're trying to save session data to storage via a database handle, the save will fail if the handle goes out of scope before the session data is flushed to storage.

So, don't do that.

o Assuming your session object goes out of scope when it doesn't

In persistent environments such as Plack, FastCGI and mod_perl, your code exits as expected, but the session object does not go out of scope in the normal way.

In cases like this, it is mandatory for you to call flush() on the session object before your code exits, since persistent environments operate in such a way that the session object's clean-up code does not get called. This means that flush() is not called automatically by DESTROY() as you would expect, because DESTROY() is not being called.

o Creating circular references anywhere in your code

In these cases, Perl's clean-up code may not run to completion, which means the session object may not have its clean-up code called at all. As above, flush() may not get called.

If you must create circular references, it's vital you debug the exit logic using a module such as Devel::Cycle before assuming the fault is with Data::Session.

o Using signal handlers

Write your code defensively, if you wish to call the session object's flush() method when a signal might affect program exit logic.

Trouble with IDs

The module uses code like if (! $self -> id), which means ids must be (Perl) true values, so undef, 0 and '' will not work.

Trouble with UUID16

While testing with UUID16 as the id generator, I got this message: ... invalid byte sequence for encoding "UTF8" ...

That's because when I create a database (in Postgres) I use "create database d_name owner d_owner encoding 'UTF8';" and UUID16 simply produces a 16 byte binary value, which is not guaranteed to be or contain a valid UTF8 character.

This also means you should never try to use 'driver:File;id:UUID16 ...', since the ids generated by this module would rarely if ever be valid as a part of a file name.

Trouble with UUID64

While testing with UUID64 as the id generator, I got this message: ... Session ids cannot contain \ or / ...

That's because I was using a File driver, and UUID's encoded in base 64 can contain /.

So, don't do that.

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Author

Copyright

Australian copyright (c) 2010, Ron Savage.

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Artistic License, a copy of which is available at:
http://www.opensource.org/licenses/index.html