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