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