lib/Plack/Session.pm

   1 package Plack::Session;
   2 use strict;
   3 use warnings;
   4
   5 use Plack::Util::Accessor qw[
   6     id
   7     store
   8     state
   9 ];
  10
  11 sub new {
  12     my ($class, %params) = @_;
  13     my $request = delete $params{'request'};
  14     $params{'id'} = $params{'state'}->get_session_id( $request );
  15     bless { %params } => $class;
  16 }
  17
  18 ## Data Managment
  19
  20 sub get {
  21     my ($self, $key) = @_;
  22     $self->store->fetch( $self->id, $key )
  23 }
  24
  25 sub set {
  26     my ($self, $key, $value) = @_;
  27     $self->store->store( $self->id, $key, $value );
  28 }
  29
  30 sub remove {
  31     my ($self, $key) = @_;
  32     $self->store->delete( $self->id, $key );
  33 }
  34
  35 ## Lifecycle Management
  36
  37 sub expire {
  38     my $self = shift;
  39     $self->store->cleanup( $self->id );
  40     $self->state->expire_session_id( $self->id );
  41 }
  42
  43 sub finalize {
  44     my ($self, $response) = @_;
  45     $self->store->persist( $self->id, $response );
  46     $self->state->finalize( $self->id, $response );
  47 }
  48
  49 1;
  50
  51 __END__
  52
  53 =pod
  54
  55 =head1 NAME
  56
  57 Plack::Session - Middleware for session management
  58
  59 =head1 SYNOPSIS
  60
  61   use Plack::Session;
  62
  63   my $store = Plack::Session::Store->new;
  64   my $state = Plack::Session::State->new;
  65
  66   my $s = Plack::Session->new(
  67       store   => $store,
  68       state   => $state,
  69       request => Plack::Request->new( $env )
  70   );
  71
  72   # ...
  73
  74 =head1 DESCRIPTION
  75
  76 This is the core session object, you probably want to look
  77 at L<Plack::Middlware::Session>, unless you are writing your
  78 own session middleware component.
  79
  80 =head1 METHODS
  81
  82 =over 4
  83
  84 =item B<new ( %params )>
  85
  86 The constructor expects keys in C<%params> for I<state>,
  87 I<store> and I<request>. The I<request> param is expected to be
  88 a L<Plack::Request> instance or an object with an equivalent
  89 interface.
  90
  91 =item B<id>
  92
  93 This is the accessor for the session id.
  94
  95 =item B<state>
  96
  97 This is expected to be a L<Plack::Session::State> instance or
  98 an object with an equivalent interface.
  99
 100 =item B<store>
 101
 102 This is expected to be a L<Plack::Session::Store> instance or
 103 an object with an equivalent interface.
 104
 105 =back
 106
 107 =head2 Session Data Storage
 108
 109 These methods delegate to appropriate methods on the C<store>
 110 to manage your session data.
 111
 112 =over 4
 113
 114 =item B<get ( $key )>
 115
 116 =item B<set ( $key, $value )>
 117
 118 =item B<remove ( $key )>
 119
 120 =back
 121
 122 =head2 Session Lifecycle Management
 123
 124 =over 4
 125
 126 =item B<expire>
 127
 128 This method can be called to expire the current session id. It
 129 will call the C<cleanup> method on the C<store> and the C<finalize>
 130 method on the C<state>, passing both of them the session id and
 131 the C<$response>.
 132
 133 =item B<finalize ( $response )>
 134
 135 This method should be called at the end of the response cycle. It
 136 will call the C<persist> method on the C<store> and the
 137 C<expire_session_id> method on the C<state>, passing both of them
 138 the session id. The C<$response> is expected to be a L<Plack::Response>
 139 instance or an object with an equivalent interface.
 140
 141 =back
 142
 143 =head1 BUGS
 144
 145 All complex software has bugs lurking in it, and this module is no
 146 exception. If you find a bug please either email me, or add the bug
 147 to cpan-RT.
 148
 149 =head1 AUTHOR
 150
 151 Stevan Little E<lt>stevan.little@iinteractive.comE<gt>
 152
 153 =head1 COPYRIGHT AND LICENSE
 154
 155 Copyright 2009 Infinity Interactive, Inc.
 156
 157 L<http://www.iinteractive.com>
 158
 159 This library is free software; you can redistribute it and/or modify
 160 it under the same terms as Perl itself.
 161
 162 =cut
 163