dancer::session::abstract(3pm) [debian man page]

Dancer::Session::Abstract(3pm)				User Contributed Perl Documentation			    Dancer::Session::Abstract(3pm)

NAME

       Dancer::Session::Abstract - abstract class for session engine

SPEC

       role
	   A Dancer::Session object represents a session engine and should provide anything needed to manipulate a session, whatever its storing
	   engine is.

       id  The session id will be written to a cookie, by default named "dancer.session", it is assumed that a client must accept cookies to be
	   able to use a session-aware Dancer webapp. (The cookie name can be change using the "session_name" config setting.)

       storage engine
	   When the session engine is enabled, a before filter takes care to initialize the appropriate session engine (according to the setting
	   "session").

	   Then, the filter looks for a cookie named "dancer.session" (or whatever you've set the "session_name" setting to, if you've used it) in
	   order to retrieve the current session object. If not found, a new session object is created and its id written to the cookie.

	   Whenever a session call is made within a route handler, the singleton representing the current session object is modified.

	   After terminating the request, a flush is made to the session object.

DESCRIPTION

       This virtual class describes how to build a session engine for Dancer. This is done in order to allow multiple session storage backends
       with a common interface.

       Any session engine must inherit from Dancer::Session::Abstract and implement the following abstract methods.

   Configuration
       These settings control how a session acts.

       session_name

       The default session name is "dancer_session". This can be set in your config file:

	   setting session_name: "mydancer_session"

       session_secure

       The user's session id is stored in a cookie.  If true, this cookie will be made "secure" meaning it will only be served over https.

       session_expires

       When the session should expire.	The format is either the number of seconds in the future, or the human readable offset from "expires" in
       Dancer::Cookie.

       By default, there is no expiration.

       session_is_http_only

       This setting defaults to 1 and instructs the session cookie to be created with the "HttpOnly" option active, meaning that JavaScript will
       not be able to access to its value.

   Abstract Methods
       retrieve($id)
	   Look for a session with the given id, return the session object if found, undef if not.

       create()
	   Create a new session, return the session object.

       flush()
	   Write the session object to the storage engine.

       destroy()
	   Remove the current session object from the storage engine.

       session_name (optional)
	   Returns a string with the name of cookie used for storing the session ID.

	   You should probably not override this; the user can control the cookie name using the "session_name" setting.

   Inherited Methods
       The following methods are not supposed to be overloaded, they are generic and should be OK for each session engine.

       build_id
	   Build a new uniq id.

       read_session_id
	   Reads the "dancer.session" cookie.

       write_session_id
	   Write the current session id to the "dancer.session" cookie.

perl v5.14.2							    2012-01-27					    Dancer::Session::Abstract(3pm)

Dancer::Session(3pm)					User Contributed Perl Documentation				      Dancer::Session(3pm)

NAME

       Dancer::Session - session engine for the Dancer framework

DESCRIPTION

       This module provides support for server-side sessions for the Dancer web framework. The session is accessible to the user via an
       abstraction layer implemented by the Dancer::Session class.

USAGE

   Configuration
       The session engine must be first enabled in the environment settings, this can be done like the following:

       In the application code:

	   # enabling the YAML-file-based session engine
	   set session => 'YAML';

       Or in config.yml or environments/$env.yml

	   session: "YAML"

       By default sessions are disabled, you must enable them before using it. If the session engine is disabled, any Dancer::Session call will
       throw an exception.

       See "Configuration" in Dancer::Session::Abstract for more configuration options.

   Route Handlers
       When enabled, the session engine can be used in a route handler with the keyword session. This keyword allows you to store/retrieve values
       from the session by name.

       Storing a value into the session:

	   session foo => 'bar';

       Retrieving that value later:

	   my $foo = session 'foo';

       You can either look for an existing item in the session storage or modify one.  Here is a simple example of two route handlers that
       implement basic "/login" and "/home" actions using the session engine.

	   post '/login' => sub {
	       # look for params and authenticate the user
	       # ...
	       if ($user) {
		   session user_id => $user->id;
	       }
	   };

	   get '/home' => sub {
	       # if a user is present in the session, let him go, otherwise redirect to
	       # /login
	       if (not session('user_id')) {
		   redirect '/login';
	       a
	   };

       Of course, you probably don't want to have to duplicate the code to check whether the user is logged in for each route handler; there's an
       example in the Dancer::Cookbook showing how to use a before filter to check whether the user is logged in before all requests, and redirect
       to a login page if not.

SUPPORTED ENGINES

       Dancer has a modular session engine that makes implementing new session backends pretty easy. If you'd like to write your own, feel free to
       take a look at Dancer::Session::Abstract.

       The following engines are supported out-of-the-box (shipped with the core Dancer distribution):

       Dancer::Session::YAML
	   A YAML file-based session backend, pretty convenient for development purposes, but maybe not the best for production needs.

       Dancer::Session::Simple
	   A very simple session backend, holding all session data in memory.  This means that sessions are volatile, and no longer exist when the
	   process exits.  This module is likely to be most useful for testing purposes, and of little use for production.

       Additionally, many more session engines are available from CPAN, including:

       Dancer::Session::Memcached
	   Session are stored in Memcached servers. This is good for production matters and is a good way to use a fast, distributed session
	   storage.  If you may be scaling up to add additional servers later, this will be a good choice.

       Dancer::Session::Cookie
	   This module implements a session engine for sessions stored entirely inside encrypted cookies (this engine doesn't use a server-side
	   storage).

       Dancer::Session::Storable
	   This backend stores sessions on disc using Storable, which offers solid performance and reliable serialisation of various data
	   structures.

       Dancer::Session::MongoDB
	   A backend to store sessions using MongoDB

       Dancer::Session::KiokuDB
	   A backend to store sessions using KiokuDB

       Dancer::Session::PSGI
	   Let Plack::Middleware::Session handle sessions; may be useful to share sessions between a Dancer app and other Plack-based apps.

DEPENDENCY

       Dancer::Session may depend on third-party modules, depending on the session engine used. See the session engine module for details.

AUTHORS

       This module has been written by Alexis Sukrieh. See the AUTHORS file that comes with this distribution for details.

LICENSE

       This module is free software and is released under the same terms as Perl itself.

SEE ALSO

       See Dancer for details about the complete framework.

perl v5.14.2							    2012-01-27						      Dancer::Session(3pm)