Doc improvements for C::P::Session

[catagits/Catalyst-Plugin-Session.git] / lib / Catalyst / Plugin / Session.pm

diff --git a/lib/Catalyst/Plugin/Session.pm b/lib/Catalyst/Plugin/Session.pm
index 372ec2f..a1d625c 100644 (file)
--- a/lib/Catalyst/Plugin/Session.pm
+++ b/lib/Catalyst/Plugin/Session.pm
@@ -75,33 +75,31 @@ sub finalize {
 sub prepare_action {
     my $c = shift;
 
-    my $ret = $c->NEXT::prepare_action;
+    if ( my $sid = $c->sessionid ) {
+        my $s = $c->{session} ||= $c->get_session_data($sid);
+        if ( !$s or $s->{__expires} < time ) {
 
-    my $sid = $c->sessionid || return;
-
-    $c->log->debug(qq/Found session "$sid"/) if $c->debug;
-
-    my $s = $c->{session} ||= $c->get_session_data($sid);
-    if ( !$s or $s->{__expires} < time ) {
-
-        # session expired
-        $c->log->debug("Deleting session $sid (expired)") if $c->debug;
-        $c->delete_session("session expired");
-        return $ret;
+            # session expired
+            $c->log->debug("Deleting session $sid (expired)") if $c->debug;
+            $c->delete_session("session expired");
+        }
+        elsif ($c->config->{session}{verify_address}
+            && $c->{session}{__address}
+            && $c->{session}{__address} ne $c->request->address )
+        {
+            $c->log->warn(
+                    "Deleting session $sid due to address mismatch ("
+                  . $c->{session}{__address} . " != "
+                  . $c->request->address . ")",
+            );
+            $c->delete_session("address mismatch");
+        }
+        else {
+            $c->log->debug(qq/Restored session "$sid"/) if $c->debug;
+        }
     }
 
-    if (   $c->config->{session}{verify_address}
-        && $c->{session}{__address}
-        && $c->{session}{__address} ne $c->request->address )
-    {
-        $c->log->warn(
-                "Deleting session $sid due to address mismatch ("
-              . $c->{session}{__address} . " != "
-              . $c->request->address . ")",
-        );
-        $c->delete_session("address mismatch");
-        return $ret;
-    }
+    $c->NEXT::prepare_action(@_);
 }
 
 sub delete_session {
@@ -170,10 +168,10 @@ sub _find_digest () {
     unless ($usable) {
         foreach my $alg (qw/SHA-1 MD5 SHA-256/) {
             eval {
-                               my $obj = Digest->new($alg);
-                               $usable = $alg;
-                               return $obj;
-                       }
+                my $obj = Digest->new($alg);
+                $usable = $alg;
+                return $obj;
+            };
         }
         $usable
           or Catalyst::Exception->throw(
@@ -209,15 +207,32 @@ storage and client side tickets required to maintain session data.
 
 =head1 SYNOPSIS
 
-    use Catalyst qw/Session Session::Store::FastMmap Session::State::Cookie/;
+    # To get sessions to "just work", all you need to do is use these plugins:
+
+    use Catalyst qw/
+      Session
+      Session::Store::FastMmap
+      Session::State::Cookie
+      /;
+
+       # you can replace Store::FastMmap with Store::File - both have sensible
+       # default configurations (see their docs for details)
+
+       # more complicated backends are available for other scenarios (DBI storage,
+       # etc)
+
+
+    # after you've loaded the plugins you can save session data
+    # For example, if you are writing a shopping cart, it could be implemented
+    # like this:
 
     sub add_item : Local {
         my ( $self, $c ) = @_;
 
         my $item_id = $c->req->param("item");
 
-        # $c->session is stored across requests, so
-        # other actions will see these values
+        # $c->session is a hash ref, a bit like $c->stash
+        # the difference is that it' preserved across requests
 
         push @{ $c->session->{items} }, $item_id;
 
@@ -229,7 +244,7 @@ storage and client side tickets required to maintain session data.
 
         # values in $c->session are restored
         $c->stash->{items_to_display} =
-            [ map { MyModel->retrieve($_) } @{ $c->session->{items} } ];
+          [ map { MyModel->retrieve($_) } @{ $c->session->{items} } ];
 
         $c->forward("MyView");
     }
@@ -249,6 +264,24 @@ made by the same client.
 
 This plugin links the two pieces together.
 
+=head1 RECCOMENDED BACKENDS
+
+=over 4
+
+=item Session::State::Cookie
+
+The only really sane way to do state is using cookies.
+
+=item Session::Store::File
+
+A portable backend, based on Cache::File.
+
+=item Session::Store::FastMmap
+
+A fast and flexible backend, based on Cache::FastMmap.
+
+=back
+
 =head1 METHODS
 
 =over 4
@@ -283,6 +316,12 @@ C<session expired>
 
 =back
 
+=back
+
+=item INTERNAL METHODS
+
+=over 4
+
 =item setup
 
 This method is extended to also make calls to
@@ -386,6 +425,26 @@ dumped objects if session ID is defined.
 
 =back
 
+=head1 USING SESSIONS DURING PREPARE
+
+The earliest point in time at which you may use the session data is after
+L<Catalyst::Plugin::Session>'s C<prepare_action> has finished.
+
+State plugins must set $c->session ID before C<prepare_action>, and during
+C<prepare_action> L<Catalyst::Plugin::Session> will actually load the data from
+the store.
+
+       sub prepare_action {
+               my $c = shift;
+
+               # don't touch $c->session yet!
+               
+               $c->NEXT::prepare_action( @_ );
+
+               $c->session;  # this is OK
+               $c->sessionid; # this is also OK
+       }
+
 =head1 CONFIGURATION
 
     $c->config->{session} = {
@@ -452,6 +511,19 @@ that it's OK for the address of the client to change. When the server sees that
 this box is checked it should delete the C<__address> sepcial key from the
 session hash when the hash is first created.
 
+=head1 AUTHORS
+
+Andy Grundman
+Christian Hansen
+Yuval Kogman, C<nothingmuch@woobling.org>
+Sebastian Riedel
+
+=head1 COPYRIGHT & LICNESE
+
+       Copyright (c) 2005 the aforementioned authors. All rights
+       reserved. This program is free software; you can redistribute
+       it and/or modify it under the same terms as Perl itself.
+
 =cut