lib/Plack/Middleware/Session.pm

   1 package Plack::Middleware::Session;
   2 use strict;
   3 use warnings;
   4
   5 use Plack::Session;
   6 use Plack::Request;
   7 use Plack::Response;
   8 use Plack::Util;
   9 use Scalar::Util;
  10
  11 use parent 'Plack::Middleware';
  12
  13 use Plack::Util::Accessor qw(
  14     state
  15     store
  16     session_class
  17 );
  18
  19 sub prepare_app {
  20     my $self = shift;
  21
  22     $self->session_class( 'Plack::Session' ) unless $self->session_class;
  23     $self->state( 'Cookie' )                 unless $self->state;
  24
  25     $self->state( $self->inflate_backend('Plack::Session::State', $self->state) );
  26     $self->store( $self->inflate_backend('Plack::Session::Store', $self->store) );
  27 }
  28
  29 sub inflate_backend {
  30     my($self, $prefix, $backend) = @_;
  31
  32     return $backend if defined $backend && Scalar::Util::blessed $backend;
  33
  34     my @class;
  35     push @class, $backend if defined $backend; # undef means the root class
  36     push @class, $prefix;
  37
  38     Plack::Util::load_class(@class)->new();
  39 }
  40
  41 sub call {
  42     my $self = shift;
  43     my $env  = shift;
  44
  45     $env->{'plack.session'} = $self->session_class->new(
  46         state   => $self->state,
  47         store   => $self->store,
  48         request => Plack::Request->new( $env )
  49     );
  50
  51     my $res = $self->app->($env);
  52     $self->response_cb($res, sub {
  53         my $res = Plack::Response->new(@{$_[0]});
  54         $env->{'plack.session'}->finalize( $res );
  55         @{$_[0]} = @{$res->finalize};
  56     });
  57 }
  58
  59 1;
  60
  61 __END__
  62
  63 =pod
  64
  65 =head1 NAME
  66
  67 Plack::Middleware::Session - Middleware for session management
  68
  69 =head1 SYNOPSIS
  70
  71   use Plack::Builder;
  72
  73   my $app = sub {
  74       return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
  75   };
  76
  77   builder {
  78       enable 'Session';
  79       $app;
  80   };
  81
  82   # Or, use the File store backend (great if you use multiprocess server)
  83   # For more options, see perldoc Plack::Session::Store::File
  84   builder {
  85       enable 'Session', store => 'File';
  86       $app;
  87   };
  88
  89 =head1 DESCRIPTION
  90
  91 This is a Plack Middleware component for session management. By
  92 default it will use cookies to keep session state and store data in
  93 memory. This distribution also comes with other state and store
  94 solutions. See perldoc for these backends how to use them.
  95
  96 =head2 State
  97
  98 =over 4
  99
 100 =item L<Plack::Session::State>
 101
 102 This will maintain session state by passing the session through
 103 the request params. It does not do this automatically though,
 104 you are responsible for passing the session param.
 105
 106 =item L<Plack::Session::State::Cookie>
 107
 108 This will maintain session state using browser cookies.
 109
 110 =back
 111
 112 =head2 Store
 113
 114 =over 4
 115
 116 =item L<Plack::Session::Store>
 117
 118 This is your basic in-memory session data store. It is volatile storage
 119 and not recommended for multiprocessing environments. However it is
 120 very useful for development and testing.
 121
 122 =item L<Plack::Session::Store::File>
 123
 124 This will persist session data in a file. By default it uses
 125 L<Storable> but it can be configured to have a custom serializer and
 126 deserializer.
 127
 128 =item L<Plack::Session::Store::Cache>
 129
 130 This will persist session data using the L<Cache> interface.
 131
 132 =item L<Plack::Session::Store::Null>
 133
 134 Sometimes you don't care about storing session data, in that case
 135 you can use this noop module.
 136
 137 =back
 138
 139 =head1 BUGS
 140
 141 All complex software has bugs lurking in it, and this module is no
 142 exception. If you find a bug please either email me, or add the bug
 143 to cpan-RT.
 144
 145 =head1 AUTHOR
 146
 147 Tatsuhiko Miyagawa
 148
 149 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
 150
 151 =head1 COPYRIGHT AND LICENSE
 152
 153 Copyright 2009 Infinity Interactive, Inc.
 154
 155 L<http://www.iinteractive.com>
 156
 157 This library is free software; you can redistribute it and/or modify
 158 it under the same terms as Perl itself.
 159
 160 =cut
 161
 162