lib/Plack/Session.pm

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