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);
50 if ($id = $self->state->extract($request) and
51 $session = $self->store->fetch($id)) {
52 $env->{'psgix.session'} = $session;
54 $id = $self->state->generate($request);
55 $env->{'psgix.session'} = {};
58 $env->{'psgix.session.options'} = { id => $id };
60 if ($self->session_class) {
61 $env->{'plack.session'} = $self->session_class->new($env);
64 my $res = $self->app->($env);
65 $self->response_cb($res, sub {
66 my $res = Plack::Response->new(@{$_[0]});
67 $self->finalize($env->{'psgix.session'}, $env->{'psgix.session.options'}, $res);
68 $res = $res->finalize;
69 $_[0]->[0] = $res->[0];
70 $_[0]->[1] = $res->[1];
75 my($self, $session, $options) = @_;
76 if ($options->{expire}) {
77 $self->store->cleanup($options->{id});
79 $self->store->store($options->{id}, $session);
84 my($self, $session, $options, $response) = @_;
86 $self->commit($session, $options) unless $options->{no_store};
87 if ($options->{expire}) {
88 $self->state->expire_session_id($options->{id}, $response);
90 $self->state->finalize($options->{id}, $response, $options);
102 Plack::Middleware::Session - Middleware for session management
110 my $session = $env->{'psgix.session'};
113 [ 'Content-Type' => 'text/plain' ],
114 [ "Hello, you've been here for ", $session->{counter}++, "th time!" ],
123 # Or, use the File store backend (great if you use multiprocess server)
124 # For more options, see perldoc Plack::Session::Store::File
126 enable 'Session', store => 'File';
132 This is a Plack Middleware component for session management. By
133 default it will use cookies to keep session state and store data in
134 memory. This distribution also comes with other state and store
135 solutions. See perldoc for these backends how to use them.
137 It should be noted that we store the current session as a hash
138 reference in the C<psgix.session> key inside the C<$env> where you can
141 B<NOTE:> As of version 0.04 the session is stored in C<psgix.session>
142 instead of C<plack.session>.
144 Also, if you set I<session_class> option (see below), we create a
145 session object out of the hash reference in C<plack.session>.
151 =item L<Plack::Session::State>
153 This will maintain session state by passing the session through
154 the request params. It does not do this automatically though,
155 you are responsible for passing the session param.
157 =item L<Plack::Session::State::Cookie>
159 This will maintain session state using browser cookies.
167 =item L<Plack::Session::Store>
169 This is your basic in-memory session data store. It is volatile storage
170 and not recommended for multiprocessing environments. However it is
171 very useful for development and testing.
173 =item L<Plack::Session::Store::File>
175 This will persist session data in a file. By default it uses
176 L<Storable> but it can be configured to have a custom serializer and
179 =item L<Plack::Session::Store::Cache>
181 This will persist session data using the L<Cache> interface.
183 =item L<Plack::Session::Store::Null>
185 Sometimes you don't care about storing session data, in that case
186 you can use this noop module.
192 The following are options that can be passed to this mdoule.
198 This is expected to be an instance of L<Plack::Session::State> or an
199 object that implements the same interface. If no option is provided
200 the default L<Plack::Session::State::Cookie> will be used.
204 This is expected to be an instance of L<Plack::Session::Store> or an
205 object that implements the same interface. If no option is provided
206 the default L<Plack::Session::Store> will be used.
208 It should be noted that this default is an in-memory volatile store
209 is only suitable for development (or single process servers). For a
210 more robust solution see L<Plack::Session::Store::File> or
211 L<Plack::Session::Store::Cache>.
213 =item I<session_class>
215 This can be used to create an actual session object in
216 C<plack.session> environment. Defaults to none, which means the
217 session object is not created but you can set C<Plack::Session> to
218 create an object for you.
224 All complex software has bugs lurking in it, and this module is no
225 exception. If you find a bug please either email me, or add the bug
232 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
234 =head1 COPYRIGHT AND LICENSE
236 Copyright 2009, 2010 Infinity Interactive, Inc.
238 L<http://www.iinteractive.com>
240 This library is free software; you can redistribute it and/or modify
241 it under the same terms as Perl itself.