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