=head1 SYNOPSIS
+ use Plack::Builder;
use Plack::Middleware::Session;
+ my $app = sub {
+ return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
+ };
+
+ builder {
+ enable 'Session';
+ $app;
+ };
+
=head1 DESCRIPTION
+This is a Plack Middleware component for session management. By
+default it will use cookies to keep session state and store data
+in memory. This distribution comes also comes with other state
+and store solutions.
+
+=head2 State
+
+=over 4
+
+=item L<Plack::Session::State>
+
+This will maintain session state by passing the session through
+the request params. It does not do this automatically though,
+you are responsible for passing the session param.
+
+=item L<Plack::Session::State::Cookie>
+
+This will maintain session state using browser cookies.
+
+=back
+
+=head2 Store
+
+=over 4
+
+=item L<Plack::Session::Store>
+
+This is your basic in-memory session data store. It is volatile storage
+and not recommended for multiprocessing environments. However it is
+very useful for development and testing.
+
+=item L<Plack::Session::Store::File>
+
+This will persist session data in a file. By default it uses
+L<Storable> but it can be configured to have a custom serializer and
+deserializer.
+
+=item L<Plack::Session::Store::CHI>
+
+This will persist session data using the L<CHI> module. This
+offers a lot of flexibility due to the many excellent L<CHI>
+drivers available.
+
+=item L<Plack::Session::Store::Null>
+
+Sometimes you don't care about storing session data, in that case
+you can use this noop module.
+
+=back
+
=head1 BUGS
All complex software has bugs lurking in it, and this module is no
use Plack::Session;
+ my $store = Plack::Session::Store->new;
+ my $state = Plack::Session::State->new;
+
+ my $s = Plack::Session->new(
+ store => $store,
+ state => $state,
+ request => Plack::Request->new( $env )
+ );
+
+ # ...
+
=head1 DESCRIPTION
+This is the core session object, you probably want to look
+at L<Plack::Middlware::Session>, unless you are writing your
+own session middleware component.
+
=head1 METHODS
=over 4
=head2 Session Data Storage
-These methods delegate to appropriate methods on the C<store>.
+These methods delegate to appropriate methods on the C<store>
+to manage your session data.
=over 4
Plack::Session::State - Basic parameter-based session state
+=head1 SYNOPSIS
+
+ use Plack::Builder;
+ use Plack::Middleware::Session;
+ use Plack::Session::State;
+
+ my $app = sub {
+ return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
+ };
+
+ builder {
+ enable 'Session',
+ state => Plack::Session::State->new;
+ $app;
+ };
+
=head1 DESCRIPTION
+This will maintain session state by passing the session through
+the request params. It does not do this automatically though,
+you are responsible for passing the session param.
+
+This should be considered the state "base" class (although
+subclassing is not a requirement) and defines the spec for
+all B<Plack::Session::State::*> modules. You will only
+need to override a couple methods if you do subclass. See
+L<Plack::Session::State::Cookie> for an example of this.
+
=head1 METHODS
=over 4
=item B<new ( %params )>
+The C<%params> can include I<session_key> and I<sid_generator>,
+however in both cases a default will be provided for you.
+
=item B<session_key>
This is the name of the session key, it default to 'plack_session'.
=item B<sid_generator>
-This is a CODE ref used to generate unique session ids.
+This is a CODE ref used to generate unique session ids, by default
+it will generate a SHA1 using fairly sufficient entropy. If you are
+concerned or interested, just read the source.
=back
Plack::Session::State::Cookie - Basic cookie-based session state
+=head1 SYNOPSIS
+
+ use Plack::Builder;
+ use Plack::Middleware::Session;
+
+ my $app = sub {
+ return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
+ };
+
+ builder {
+ enable 'Session'; # Cookie is the default state
+ $app;
+ };
+
=head1 DESCRIPTION
This is a subclass of L<Plack::Session::State> and implements it's
-full interface.
+full interface. This is the default state used in
+L<Plack::Middleware::Session>.
=head1 METHODS
=item B<new ( %params )>
+The C<%params> can include I<path>, I<domain>, I<expires> and
+I<secure> options, as well as all the options accepted by
+L<Plack::Session::Store>.
+
=item B<path>
+Path of the cookie, this defaults to "/";
+
=item B<domain>
+Domain of the cookie, if nothing is supplied then it will not
+be included in the cookie.
+
=item B<expires>
+Expiration time of the cookie, if nothing is supplied then it will
+not be included in the cookie.
+
=item B<secure>
+Secure flag for the cookie, if nothing is supplied then it will not
+be included in the cookie.
+
=back
=head1 BUGS
Plack::Session::Store - Basic in-memory session store
+=head1 SYNOPSIS
+
+ use Plack::Builder;
+ use Plack::Middleware::Session;
+ use Plack::Session::Store;
+
+ my $app = sub {
+ return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
+ };
+
+ builder {
+ enable 'Session'; # this is the defalt store
+ $app;
+ };
+
=head1 DESCRIPTION
+This is a very basic in-memory session data store. It is volatile
+storage and not recommended for multiprocessing environments. However
+it is very useful for development and testing.
+
+This should be considered the store "base" class (although
+subclassing is not a requirement) and defines the spec for
+all B<Plack::Session::Store::*> modules. You will only
+need to override a couple methods if you do subclass. See
+the other B<Plack::Session::Store::*> for examples of this.
+
=head1 METHODS
=over 4
=item B<new ( %params )>
+No parameters are expected to this constructor.
+
=back
=head2 Session Data Management
+These methods fetch data from the session storage. It can only fetch,
+store or delete a single key at a time.
+
=over 4
=item B<fetch ( $session_id, $key )>
=head1 DESCRIPTION
+This will persist session data using the L<CHI> module. This
+offers a lot of flexibility due to the many excellent L<CHI>
+drivers available.
+
This is a subclass of L<Plack::Session::Store> and implements
it's full interface.
Plack::Session::Store::File - Basic file-based session store
+=head1 SYNOPSIS
+
+ use Plack::Builder;
+ use Plack::Middleware::Session;
+ use Plack::Session::Store::File;
+
+ my $app = sub {
+ return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
+ };
+
+ builder {
+ enable 'Session',
+ store => Plack::Session::Store::File->new(
+ dir => '/path/to/sessions'
+ );
+ $app;
+ };
+
+ # with custom serializer/deserializer
+
+ builder {
+ enable 'Session',
+ store => Plack::Session::Store::File->new(
+ dir => '/path/to/sessions',
+ # YAML takes it's args the opposite order
+ serializer => sub { YAML::DumpFile( reverse @_ ) },
+ deserializer => sub { YAML::LoadFile( @_ ) },
+ );
+ $app;
+ };
+
=head1 DESCRIPTION
+This implements a basic file based storage for session data. By
+default it will use L<Storable> to serialize and deserialize the
+data, but this can be configured easily.
+
+This is a subclass of L<Plack::Session::Store> and implements
+it's full interface.
+
=head1 METHODS
=over 4
=item B<new ( %params )>
+The C<%params> can include I<dir>, I<serializer> and I<deserializer>
+options. It will check to be sure that the I<dir> is writeable for
+you.
+
=item B<dir>
+This is the directory to store the session data files in, if nothing
+is provided then "/tmp" is used.
+
=item B<serializer>
+This is a CORE reference that implements the serialization logic.
+The CODE ref gets two arguments, the C<$value>, which is a HASH
+reference to be serialized, and the C<$file_path> to save it to.
+It is not expected to return anything.
+
=item B<deserializer>
+This is a CORE reference that implements the deserialization logic.
+The CODE ref gets one argument, the C<$file_path> to load the data
+from. It is expected to return a HASH reference.
+
=back
=head1 BUGS
Plack::Session::Store::Null - Null store
+=head1 SYNOPSIS
+
+ use Plack::Builder;
+ use Plack::Middleware::Session;
+ use Plack::Session::Store::Null;
+
+ my $app = sub {
+ return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello Foo' ] ];
+ };
+
+ builder {
+ enable 'Session',
+ store => Plack::Session::Store::Null->new;
+ $app;
+ };
+
=head1 DESCRIPTION
Sometimes you don't want to store anything in your sessions, but
L<Plack::Session> requires a C<store> instance, so you can use this
one and all methods will return null.
+This is a subclass of L<Plack::Session::Store> and implements
+it's full interface.
+
=head1 BUGS
All complex software has bugs lurking in it, and this module is no
projects / catagits/Web-Session.git / commitdiff