NAME
CGI::Session::AUS - Session management for Schema::RDBMS::AUS
SYNOPSIS
use CGI::Session::AUS;
$ENV{AUS_DB_DSN} = 'DBI:Pg:';
$session = new CGI::Session::AUS();
$session->login($user, $password);
$session->param('foo');
etc..DESCRIPTION
CGI::Session::AUS is a subclass of CGI::Session that provides access to sessions being used under Schema::RDBMS::AUS. It automatically configures the session object to use AUS's driver, and also provides access to the extra information that is stored on a session in the AUS schema.
USAGE
Create a CGI::Session::AUS object the same way as you would create a CGI::Session object; just always make sure the driver is specified as "aus". By default, CGI::Session::AUS will use the Storable serializer to save information to the database. For full details on the CGI::Session interface, see CGI::Session. The extensions that CGI::Session::AUS provides are described below:
USER METHODS
The following methods help tie sessions to users (also see the "user" method in "METADATA METHODS" below):
- login($user, $pass, %log_options)
-
Attempt to log a user in with the given username and password. %log_options is a hash of additional options to pass to Schema::RDBMS::AUS::User's login method. Some options (ip, etc) will be automatically set for you by
log_opts, documented below. Any additional parameters passed in will end up in the user's authentication log.Logging a user in implicitly flushes the session to the database.
- logout(%log_options)
-
If this session has a logged in user, log that user out and disassociate them from the session.
Logging a user out implicitly flushes the session to the database.
METADATA METHODS
The following methods can be used to obtain extra information about the session:
- user
-
Returns a Schema::RDBMS::AUS::User object if this session is logged in,
undefotherwise.When a session is flushed, if there is an associated user, that user is always saved as well. However, a session is only flushed if it has changed. If you have only changed the user and have not changed the session, you will have to save the user yourself!
- created
-
Returns the time that this session was created. The format of this time will depend on your database engine. Future versions may convert this to epoch for you (I'm still debating this).
- time_last
-
Returns the last time that this session was used.
UTILITY METHODS
These methods are used internally by CGI::Session::AUS, but you might find them nifty too:
- remote_ip
-
Returns the remote IP address detected for this session. This comes from one of two places:
- The REMOTE_ADDR environment variable
-
This is set in most CGI and mod_perl environments and is considered the most accurate.
- The _SESSION_REMOTE_ADDR session parameter
-
CGI::Session does it's own IP detection and puts the detected remote IP here. If REMOTE_ADDR is not set, we will use this as the remote IP.
If neither of these sources are filled in, remote_ip returns
undef. - log_opts
-
Returns a hash containing options suitable to pass to Schema::RDBMS::AUS::User's
loginandlogoutmethods, to provide information to write in the authentication log. The following key/value pairs can be returned:
OVERRIDDEN METHODS
The whole purpose of CGI::Session::AUS is to integrate Schema::RDBMS::AUS::User with CGI::Session. In order to facilitate this, the following CGI::Session methods have been overridden in CGI::Session::AUS:
- flush
-
When a CGI::Session::AUS session is flushed, we store some meta-data about the session in the AUS schema as well.
When a deleted session is flushed, we delete the metadata from the session object along with the regular session data.
- load
-
If a session ID is not specified, we look in the AUS_SESSION_ID environment variable for a default value. This variable is set by higher-level handlers like Apache2::AUS.
We use CGI::Session::Serialize::yaml as our default serializer to encourage compatibility with other programming languages.
Whenever a session is loaded, we load it's metadata (including a Schema::RDBMS::AUS::User object if the session is logged in) along with it.
AUTHOR
Tyler "Crackerjack" MacDonald <japh@crackerjack.net>
LICENSE
Copyright 2006 Tyler "Crackerjack" MacDonald <japh@crackerjack.net>
This is free software; You may distribute it under the same terms as perl itself.