1 package Plack::Middleware::Session;
6 our $AUTHORITY = 'cpan:STEVAN';
13 use parent 'Plack::Middleware';
15 use Plack::Util::Accessor qw(
24 $self->state( 'Cookie' ) unless $self->state;
25 $self->state( $self->inflate_backend('Plack::Session::State', $self->state) );
26 $self->store( $self->inflate_backend('Plack::Session::Store', $self->store) );
28 Plack::Util::load_class($self->session_class) if $self->session_class;
32 my($self, $prefix, $backend) = @_;
34 return $backend if defined $backend && Scalar::Util::blessed $backend;
37 push @class, $backend if defined $backend; # undef means the root class
40 Plack::Util::load_class(@class)->new();
47 my $request = Plack::Request->new($env);
49 my($id, $session) = $self->get_session($request);
50 if ($id && $session) {
51 $env->{'psgix.session'} = $session;
53 $id = $self->generate_id($request);
54 $env->{'psgix.session'} = {};
57 $env->{'psgix.session.options'} = { id => $id };
59 if ($self->session_class) {
60 $env->{'plack.session'} = $self->session_class->new($env);
63 my $res = $self->app->($env);
64 $self->response_cb($res, sub {
65 my $res = Plack::Response->new(@{$_[0]});
66 $self->finalize($request, $res);
67 $res = $res->finalize;
68 $_[0]->[0] = $res->[0];
69 $_[0]->[1] = $res->[1];
74 my($self, $request) = @_;
76 my $id = $self->state->extract($request) or return;
77 my $session = $self->store->fetch($id) or return;
79 return ($id, $session);
83 my($self, $request) = @_;
84 $self->state->generate($request);
88 my($self, $session, $options) = @_;
89 if ($options->{expire}) {
90 $self->store->remove($options->{id});
92 $self->store->store($options->{id}, $session);
97 my($self, $request, $response) = @_;
99 my $session = $request->env->{'psgix.session'};
100 my $options = $request->env->{'psgix.session.options'};
102 $self->commit($session, $options) unless $options->{no_store};
103 if ($options->{expire}) {
104 $self->expire_session($options->{id}, $response, $session, $options);
106 $self->save_state($options->{id}, $response, $session, $options);
111 my($self, $id, $res, $session, $options) = @_;
112 $self->state->expire_session_id($options->{id}, $res, $options);
116 my($self, $id, $res, $session, $options) = @_;
117 $self->state->finalize($id, $res, $options);
128 Plack::Middleware::Session - Middleware for session management
136 my $session = $env->{'psgix.session'};
139 [ 'Content-Type' => 'text/plain' ],
140 [ "Hello, you've been here for ", $session->{counter}++, "th time!" ],
149 # Or, use the File store backend (great if you use multiprocess server)
150 # For more options, see perldoc Plack::Session::Store::File
152 enable 'Session', store => 'File';
158 This is a Plack Middleware component for session management. By
159 default it will use cookies to keep session state and store data in
160 memory. This distribution also comes with other state and store
161 solutions. See perldoc for these backends how to use them.
163 It should be noted that we store the current session as a hash
164 reference in the C<psgix.session> key inside the C<$env> where you can
167 B<NOTE:> As of version 0.04 the session is stored in C<psgix.session>
168 instead of C<plack.session>.
170 Also, if you set I<session_class> option (see below), we create a
171 session object out of the hash reference in C<plack.session>.
177 =item L<Plack::Session::State>
179 This will maintain session state by passing the session through
180 the request params. It does not do this automatically though,
181 you are responsible for passing the session param.
183 =item L<Plack::Session::State::Cookie>
185 This will maintain session state using browser cookies.
193 =item L<Plack::Session::Store>
195 This is your basic in-memory session data store. It is volatile storage
196 and not recommended for multiprocessing environments. However it is
197 very useful for development and testing.
199 =item L<Plack::Session::Store::File>
201 This will persist session data in a file. By default it uses
202 L<Storable> but it can be configured to have a custom serializer and
205 =item L<Plack::Session::Store::Cache>
207 This will persist session data using the L<Cache> interface.
209 =item L<Plack::Session::Store::Null>
211 Sometimes you don't care about storing session data, in that case
212 you can use this noop module.
218 The following are options that can be passed to this mdoule.
224 This is expected to be an instance of L<Plack::Session::State> or an
225 object that implements the same interface. If no option is provided
226 the default L<Plack::Session::State::Cookie> will be used.
230 This is expected to be an instance of L<Plack::Session::Store> or an
231 object that implements the same interface. If no option is provided
232 the default L<Plack::Session::Store> will be used.
234 It should be noted that this default is an in-memory volatile store
235 is only suitable for development (or single process servers). For a
236 more robust solution see L<Plack::Session::Store::File> or
237 L<Plack::Session::Store::Cache>.
239 =item I<session_class>
241 This can be used to create an actual session object in
242 C<plack.session> environment. Defaults to none, which means the
243 session object is not created but you can set C<Plack::Session> to
244 create an object for you.
250 All complex software has bugs lurking in it, and this module is no
251 exception. If you find a bug please either email me, or add the bug
258 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
260 =head1 COPYRIGHT AND LICENSE
262 Copyright 2009, 2010 Infinity Interactive, Inc.
264 L<http://www.iinteractive.com>
266 This library is free software; you can redistribute it and/or modify
267 it under the same terms as Perl itself.