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