NAME
Apache2::Controller::Session - Apache2::Controller PerlHeaderParserHandler for Apache::Session
SYNOPSIS
Set your A2C session subclass as a PerlHeaderParserHandler.
This example assumes use of Apache2::Controller::Session::Cookie.
# cookies will get path => /somewhere
<Location /somewhere>
PerlOptions +SetupEnv # temporary until Directives work
# see Apache2::Controller::Dispatch for dispatch subclass info
PerlInitHandler MyApp::Dispatch
PerlSetEnv A2CSessionCookieName myappsessid
PerlSetEnv A2CSessionClass Apache::Session::MySQL
PerlHeaderParserHandler MyApp::Session
</Location>In controllers, tied session hash is $r->pnotes->{session}.
In this example above, you implement get_options() in your session subclass to return the options hashref to tie() for Apache::Session::MySQL.
If you do not implement get_options(), it will try to create directories to use Apache::Session::File using /tmp/a2c_sessions/<request hostname>/ and /var/lock/a2c_sessions/<request hostname>
Warning! Kludgey PerlSetEnv syntax will be replaced by directives when the directives classes work.
CONFIG ALTERNATIVE 1: directives or environment variables
If you do not implement a special getoptions() method or use settings other than these, these are the default:
<Location /elsewhere>
PerlHeaderParserHandler MyApp::ApacheSessionFile
# until directives work, use this kludgey PerlSetEnv syntax:
PerlSetEnv A2CSessionClass Apache::Session::File
PerlSetEnv A2CSessionOptions "Directory /tmp/sessions LockDirectory /var/lock/sessions"
# under future fixed Apache2::Controller::Directives directives
A2CSessionClass Apache::Session::File
A2CSessionOptions Directory /tmp/sessions
A2CSessionOptions LockDirectory /var/lock/sessions
</Location>Until directives work and the kludgey PerlSetEnv syntax goes away, spaces are not allowed in the argument values. Warning! The kludgey PerlSetEnv syntax will go away when directives work properly.
CONFIG ALTERNATIVE 2: YourApp::YourSessionClass->get_options()
Implement get_options() in your subclass to return the final options hashref for your Apache::Session session type.
For example, if your app uses DBIx::Class, maybe you want to go ahead and init your schema so you can get the database handle directly and pass that to your session class. or if you use Apache::DBI, connect and put it in pnotes to save for your own use later.
Here's a code example for Location /somewhere above:
package MyApp::Session;
use strict;
use warnings FATAL => 'all';
use base qw( Apache2::Controller::Session::Cookie );
use English '-no_match_vars';
use Apache2::Controller::X;
sub get_options {
my ($self) = @_; # $self inherits Apache2::Controller::Session,
# Apache2::Controller::Session::Cookie,
# Apache2::Request, Apache2::RequestRec, etc...
eval {
$self->pnotes->{dbh} ||= DBI->connect(
'dbi:mysql:database=myapp;host=mydbhost';
'myuser', 'mypassword'
);
};
Apache2::Controller::X->throw("cannot connect to DB: $EVAL_ERROR")
if $EVAL_ERROR;
my $dbh = $self->pnotes->{dbh}; # save handle for later use
# in controllers, etc.
return {
Handle => $dbh,
LockHandle => $dbh,
};
}If you do it this way or use Apache::DBI, be careful about transactions. See "DATABASE TRANSACTION SAFETY" below.
# ...In your controller module, access the session in $self->pnotes->{session}.
package MyApp::Controller::SomeWhere::Overtherainbow;
# ...
sub default {
my ($self) = @_;
my $session = $self->pnotes->{session};
$session->{foo} = 'bar';
# session will be saved by a PerlCleanupHandler
# that was automatically pushed by Apache2::Controller::Session
# and in my example
return Apache2::Const::HTTP_OK;
}DESCRIPTION
Use an Apache2::Controller::Session tracker module and specify your Apache::Session type store.
Instead of having a bunch of different options for all the different Apache::Session types, it's easier for me to make you provide a method session_options() in your subclass that will return a has of the appropriate options for your chosen session store.
DATABASE TRANSACTION SAFETY
When this handler runs, it ties the session into a special hash that it keeps internally, and loads a copy into $r->pnotes->{session}. So, modifying the session hash is fine, as long as you do not dereference it, or as long as you save your changes back to $r->pnotes->{session}.
No changes are auto-committed. The one in pnotes is copied back into the tied session hash in a PerlCleanupHandler, after the server finishes output and closes the connection to the client. If the connection is detected to be aborted in the PerlLogHandler phase, changes are NOT saved into the session object in the PerlCleanupHandler phase.
If you implemented get_options() as per above and decided to save your $dbh for later use in your controllers, feel free to start transactions and use them normally. Just make sure you use "eval" in perlfunc correctly and roll back or commit your transactions.
If you decide to push a PerlCleanupHandler to roll back transactions for broken connections or something, be aware that this handler pushes a cleanup handler closure that saves the copy in pnotes back into the tied hash. So, depending on what order you want, whether you want to save the session before or after your database cleanup handler, you may have to re-order the PerlCleanupHandler stack with "get_handlers" in Apache2::RequestUtil and set_handlers().
IMPLEMENTING TRACKER SUBCLASSES
See Apache2::Controller::Session::Cookie for how to implement a custom tracker subclass. This implements get_session_id() which gets a session id from a cookie, and set_session_id() which sets the session id in the cookie.
Perhaps some custom tracker subclass would implement get_session_id() to get the session_id out of the request query params, and set_session_id() would push a PerlOutputFilterHandler to post-process all other handler output and append the session id param onto any url links that refer to our site. That would be cool... release your own plug-in. If you wanted to do it with combined cookies and url params in this way you could overload get_session_id() and set_session_id(), etc. etc.
METHODS
process
The process() method attaches or creates a session, and pushes a PerlCleanupHandler closure to save the session after the end of the request.
It sets the session id cookie with an expiration that you set in your subclass as our $expiration = ... in a format that is passed to Apache2::Cookie. (i.e. '3M', '2D', etc.) Don't set that if you want them to expire at the end of the browser session.
get_options
The default get_options method uses Apache2::Session::File.
Default settings try to create subdirectories under /tmp/a2c_sessions and /var/lock/a2c_sessions which are named for the hostname of the current request, such as the virtual host name.
If you use Windows or want to do something differently, use your own settings or overload get_options().
If you use Windows, you're chicken. Live free!
SEE ALSO
Apache2::Controller::Session::Cookie,
Apache2::Controller::Dispatch,
AUTHOR
Mark Hedges, <hedges at scriptdolphin.org>
COPYRIGHT & LICENSE
Copyright 2008 Mark Hedges, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.