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, undef otherwise.

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 login and logout methods, to provide information to write in the authentication log. The following key/value pairs can be returned:

ip

The user's remote IP address, as returned by remote_ip (documented above).

session_id

This session's unique ID string.

name

If we are logged in, the logged in user's name.

id

If we are logged in, the logged in user's ID.

_dbh

Our database handle, so that it can be shared with the user object.

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.

SEE ALSO

CGI::Session, Schema::RDBMS::AUS, Schema::RDBMS::AUS::User.