From: Stevan Little Date: Sun, 13 Dec 2009 02:12:19 +0000 (-0500) Subject: bunch more docs X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FWeb-Session.git;a=commitdiff_plain;h=3d92cf47c8b9eca07fcbf2bb856963f49c68228e bunch more docs --- diff --git a/lib/Plack/Middleware/Session.pm b/lib/Plack/Middleware/Session.pm index 978c5ae..9bbe61c 100644 --- a/lib/Plack/Middleware/Session.pm +++ b/lib/Plack/Middleware/Session.pm @@ -53,10 +53,70 @@ Plack::Middleware::Session - Middleware for session management =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 + +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 + +This will maintain session state using browser cookies. + +=back + +=head2 Store + +=over 4 + +=item L + +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 + +This will persist session data in a file. By default it uses +L but it can be configured to have a custom serializer and +deserializer. + +=item L + +This will persist session data using the L module. This +offers a lot of flexibility due to the many excellent L +drivers available. + +=item L + +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 diff --git a/lib/Plack/Session.pm b/lib/Plack/Session.pm index 6473b27..7c0a60c 100644 --- a/lib/Plack/Session.pm +++ b/lib/Plack/Session.pm @@ -60,8 +60,23 @@ Plack::Session - Middleware for session management 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, unless you are writing your +own session middleware component. + =head1 METHODS =over 4 @@ -91,7 +106,8 @@ an object with an equivalent interface. =head2 Session Data Storage -These methods delegate to appropriate methods on the C. +These methods delegate to appropriate methods on the C +to manage your session data. =over 4 diff --git a/lib/Plack/Session/State.pm b/lib/Plack/Session/State.pm index 440be43..10a1368 100644 --- a/lib/Plack/Session/State.pm +++ b/lib/Plack/Session/State.pm @@ -70,21 +70,52 @@ __END__ 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 modules. You will only +need to override a couple methods if you do subclass. See +L for an example of this. + =head1 METHODS =over 4 =item B +The C<%params> can include I and I, +however in both cases a default will be provided for you. + =item B This is the name of the session key, it default to 'plack_session'. =item B -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 diff --git a/lib/Plack/Session/State/Cookie.pm b/lib/Plack/Session/State/Cookie.pm index 6440ebd..e723d8e 100644 --- a/lib/Plack/Session/State/Cookie.pm +++ b/lib/Plack/Session/State/Cookie.pm @@ -51,10 +51,25 @@ __END__ 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 and implements it's -full interface. +full interface. This is the default state used in +L. =head1 METHODS @@ -62,14 +77,29 @@ full interface. =item B +The C<%params> can include I, I, I and +I options, as well as all the options accepted by +L. + =item B +Path of the cookie, this defaults to "/"; + =item B +Domain of the cookie, if nothing is supplied then it will not +be included in the cookie. + =item B +Expiration time of the cookie, if nothing is supplied then it will +not be included in the cookie. + =item B +Secure flag for the cookie, if nothing is supplied then it will not +be included in the cookie. + =back =head1 BUGS diff --git a/lib/Plack/Session/Store.pm b/lib/Plack/Session/Store.pm index b742d0d..572730b 100644 --- a/lib/Plack/Session/Store.pm +++ b/lib/Plack/Session/Store.pm @@ -45,18 +45,48 @@ __END__ 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 modules. You will only +need to override a couple methods if you do subclass. See +the other B for examples of this. + =head1 METHODS =over 4 =item B +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 diff --git a/lib/Plack/Session/Store/CHI.pm b/lib/Plack/Session/Store/CHI.pm index 6a155ec..1e2956b 100644 --- a/lib/Plack/Session/Store/CHI.pm +++ b/lib/Plack/Session/Store/CHI.pm @@ -79,6 +79,10 @@ Plack::Session::Store::CHI - CHI session store =head1 DESCRIPTION +This will persist session data using the L module. This +offers a lot of flexibility due to the many excellent L +drivers available. + This is a subclass of L and implements it's full interface. diff --git a/lib/Plack/Session/Store/File.pm b/lib/Plack/Session/Store/File.pm index c2926da..63b569e 100644 --- a/lib/Plack/Session/Store/File.pm +++ b/lib/Plack/Session/Store/File.pm @@ -82,20 +82,74 @@ __END__ 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 to serialize and deserialize the +data, but this can be configured easily. + +This is a subclass of L and implements +it's full interface. + =head1 METHODS =over 4 =item B +The C<%params> can include I, I and I +options. It will check to be sure that the I is writeable for +you. + =item B +This is the directory to store the session data files in, if nothing +is provided then "/tmp" is used. + =item B +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 +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 diff --git a/lib/Plack/Session/Store/Null.pm b/lib/Plack/Session/Store/Null.pm index 3ab6ccb..139a44b 100644 --- a/lib/Plack/Session/Store/Null.pm +++ b/lib/Plack/Session/Store/Null.pm @@ -19,12 +19,31 @@ __END__ 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 requires a C instance, so you can use this one and all methods will return null. +This is a subclass of L and implements +it's full interface. + =head1 BUGS All complex software has bugs lurking in it, and this module is no