bionic (3) Dancer::Session.3pm.gz

NAME

       Dancer::Session - session engine for the Dancer framework

VERSION

       version 1.3202

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';
               }
           };

       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
           serialization 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.

AUTHOR

       Dancer Core Developers

COPYRIGHT AND LICENSE

       This software is copyright (c) 2010 by Alexis Sukrieh.

       This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5
       programming language system itself.