Better documentation of when exactly session related things happen

diff --git a/lib/Catalyst/Plugin/Session.pm b/lib/Catalyst/Plugin/Session.pm
index 55c5b6f..6422027 100644 (file)
--- a/lib/Catalyst/Plugin/Session.pm
+++ b/lib/Catalyst/Plugin/Session.pm
@@ -384,6 +384,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} = {

diff --git a/lib/Catalyst/Plugin/Session/State.pm b/lib/Catalyst/Plugin/Session/State.pm
index c6cf829..3b8cbe9 100644 (file)
--- a/lib/Catalyst/Plugin/Session/State.pm
+++ b/lib/Catalyst/Plugin/Session/State.pm
@@ -32,19 +32,22 @@ reason only.
 
 =head1 WRITING STATE PLUGINS
 
-To write a session state plugin you usually need to extend C<finalize> and
-C<prepare> (or e.g. C<prepare_action>) to do two things:
+To write a session state plugin you usually need to extend two methods:
 
 =over 4
 
-=item *
+=item prepare_(action|cookies|whatever)
 
-Set C<sessionid> (accessor) at B<prepare> time using data in the request
+Set C<sessionid> (accessor) at B<prepare> time using data in the request.
 
-=item *
+Note that this must happen B<before> other C<prepare_action> instances, in
+order to get along with L<Catalyst::Plugin::Session>. Overriding
+C<prepare_cookies> is probably the stablest approach.
 
-Modify the response at B<finalize> to include the session ID if C<sessionid> is
-defined.
+=item finalize
+
+Modify the response at to include the session ID if C<sessionid> is defined,
+using whatever scheme you use. For example, set a cookie, 
 
 =back