The Session
The Session file saves the state of the click, having the same function
as a cookie, with the advantage of being on the server side. At this time,
we only support the file form of the session; support for SQL can be built
in at a later date.
This file contains different records, in a pipe-delimited format. The
first value of a record is the record title, the second one is the time
stamp of the last time the session file was accessed. Anything else after,
is the data record itself.
Valid records for the session file
auth_session
This record contains the authentication data, and includes everything
from the user database, except for the password and the time stamp of
the record creation. It is used for authentication purposes only.
cart_id
This record has only one value, which is the CartID. It is used to re-create
the cart if missing or was expired.
save_form_fields
This record saves all the form fields, that could be used to build a
link, to get back where we were last time. The form fields are being saved
as an escaped, ready-to use URL.
There is one routine taking advantage of it right now, the _SaveFormFields()
found in the AuthLib.pm.
This particular routine checks for some extra fields, specific to the
authentication process. There is a more generic routine that can be implemented
anywhere, located in the MainLib.pm, with the name: SaveFormFieldsAsLink().
It can be called with the following syntax:
$SLib->_set('save_form_fields', _SaveFormFieldsAsLink($S, $FX));
Of course, since the $Slib->_set() method does not really write
anything to the file, you will have to use the following call somewhere
in your path, cause that really commits the data to the session file:
$SLib->_update();
order_data
This record contains data regarding the order, like weight, total amount,
shipping method and price, payment mode, etc. It is currently used only
in the order form process, but could be addressed from other libraries
as needed, like the library displaying the cart.
order_form_data
This record contains all the form fields related to the order form. It
restores the last state of the order form fields, so the user does not
have to re-enter them.
search_results
This is the only mulitiple field allowed right now in the session file.
It saves the result of a certain search. For the time being, we only save
the item id's, and of course, the keywords and the other parameters of
the search process that returned those hits.
The search record has a lower timeout than all the other records (20 mins).
That should be enough to allow the user to browse through the search results.
It is a big time saver for elaborate searches, since, once cached in the
session file, the "next 10"-type of click will run a faster
search, by item ID only.
Editing the session properties
The session file setup is described in the ShopSetup.pm, under
the hash "$DBSession", which corresponds to the entry:
$S->{-DB}->{'session'}.
As you can see in the structure of the hash, it is pretty much similar
with other database descriptions, with the difference that this one can
contain multiple records. Here is a description of the keys of this hash:
-LIFESPAN - sets the session file lifespan. The default value
is 12 hours (0.5 days), but you can set it to what you want
-FIELDS - describes the names of the fields for every record
-RECORD_TYPE - describes the single and the multiple records
-RECORD_KEYS - multiple fields can have a key field (like in the
entry for the search field). This key holds the reference to a hash of
key fields for the multiple records used in the session.
-RECORD_EXPIRES - every field has an expiration time, in seconds.
For the sake of a correct functionality, please keep the following syncronization
and order:
- the fields auth_session and cart_id should have the same value, and
expire last
- the fields order_data, order_form_data, and save_form_fields
should come next, and also have the same value
- the entries for search_results can be of any value, but you might want
to keep it low, so you can minimize the space taken by the session files.
The package that handles the session file
Now that we know a bit what are we working with, let's describe the usage
of the package that handles the session file. The package is named SessionLib.pm.
It does have a constructor, and the call is as follows:
my $Session =
$S->{-LIB_SESSION} =
new SessionLib($S->{-DB}{'session'}, $SessionID);
As you can see, save the handle to the object in the main hash, under
the key "-LIB_SESSION". You can find this constructor
call in the ReadHeader() routine, in the main script, store.cgi.
The session ID will be generated if not provided, by first checking the
list of the session files available, and after deleting the old session
files. If the file does not exist, the routine assumes that it expired
and it reuses the ID to create the file.
The keys available for the session object hash
As expected, this object uses the database hash described before to build
its keys. All the keys in the database description are imported, or replaced
with defaults, if missing. If one of the required keys is missing, the
script will exit with an error. The keys that are required are:
- -FILE_PATH
- -FIELDS
- -RECORD_TYPE
- -RECORD_EXPIRES
Additionally, there are a couple of keys created during processing:
- -CHANGED - it returns the status of the session file, and is
set on 1 if any of the keys contents changed. Note further in the description
of the methods, that the changes are not written automatically back
to the file.
- -DATA - it contains all the data in the session file, in form
of a hash. The fields are saved as array references, the active payload.
Since we will update the record time mark whenever we write it back,
we do not save in this hash. The multiple fields are saved as the reference
to an array of array references, to all the fields.
The methods available for the session object
Additional to the constructor, the SessionLib.pm has the following methods:
_read()
This method returns the value of a certain record. If the session file
contents is cached in the -DATA key, this value is returned instead.
The call has the following format:
my $CartID = $Session->_read('cart_id');
my ($UserID,
$Access,
$AuthEmail) = $Session->_read('auth_session');
_set()
This method sets the value of a field in the -DATA hash. The call
has the following format:
$Session->_set('cart_id', $CartID);
$Session->_set('form_data', \@FormDataFieldValues);
The changes affect only the -DATA key of the object, and are not
written back to the file. Once the value is set, the key -CHANGED
is set on 1.
_write()
The _write() method sets the value of a field in the -DATA hash,
and writes back the whole hash to the session file. The call has the following
format:
$Session->_write('cart_id', $CartID) and Carp::croak($Err);
As we can see, it returns "1" if the operation failed,
which can be used to exit with the error, or log it to the error log.
Once the changes are saved, the key -CHANGED is reset on 0.
_update()
The _update() method writes back the session hash, regardless if it was
changed or not. It can be used to refresh the time mark for all the records.
The call has the following format:
$Session->_update() and Carp::croak($Err);
|
