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