NAME

Apache::Stateful - Perl extension for simplistic HTTP state management under mod_perl

SYNOPSIS

use Apache::Stateful qw(set_dbparams start_session end_session);

set_dbparams(
  Username   => 'nobody',
  Password   => '',
  DataSource => 'dbi:mysql:database=sessions:mysql_compression=1');

set_cookie_expire('+1h');

my $sess = start_session();

$sess->{count}++;

end_session();

DESCRIPTION

A number of excellent modules have been released that make session management easier to implement under mod_perl.

This goal of this module is to tie together some of the existing modules (Apache::Session::DBI and Apache::Cookie) to perform simple database driven state for your mod_perl project.

I've tried to keep it as simple as possible. We keep state via cookies, pathinfo, and/or HTTP_REFERER. We'll prefer the cookie but in the absence of a cookie but presence of pathinfo, we'll use that (in case the user doesn't accept them). In the event of an absolute link, we maintain the session id without cookies through the HTTP_REFERER field.

You need to have a database with a 'sessions' table. The table should contain the following fields (per the Apache::Session::DBIStore POD):

id char(16)
length int(11)
a_session text

SUBROUTINES

set_dbparams HASH

This function sets the username, password, and DBI data source used to access the database where session data is stored. It accepts up to three named parameters, 'Username', 'Password', and 'DataSource'.

Failure to pass a parameter results in the use of a default value. The default values are provided in the SYNOPSIS above.

set_cookie_expire STRING

The cookies expire by default in one hour. If you would like to change this, call this function with an expire string. See the POD for CGI::Cookie to get an idea of how this works. (e.g. '+1h' is one hour)

start_session

This function initializes the session and returns the hash reference that is the session object. Simply add keys to this hash and they will be stored to the database for later retrieval.

end_session

You must call this function at the end of your code or the changed values in the session hash will not be written back to the database.

Apache children seem to hang if you don't call this function!

BUGS

To err is human.. if you find any, let me know. I'm using this in production code but YMMV. There is no warranty express or implied but if you have problems, send me an e-mail and I might be able to help.

AUTHOR

Benjamin R. Ginter, bginter@asicommunications.com

Copyright (c) 1999 Benjamin R. Ginter. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

mod_perl, Apache::Session, Apache::Cookie, perl(1).