lib/Plack/Session.pm

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