.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Dancer::Session 3pm"
.TH Dancer::Session 3pm "2015-11-07" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dancer::Session \- session engine for the Dancer framework
.SH "VERSION"
.IX Header "VERSION"
version 1.3202
.SH "DESCRIPTION"
.IX Header "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.
.SH "USAGE"
.IX Header "USAGE"
.SS "Configuration"
.IX Subsection "Configuration"
The session engine must be first enabled in the environment settings, this can
be done like the following:
.PP
In the application code:
.PP
.Vb 2
\&    # enabling the YAML\-file\-based session engine
\&    set session => \*(AqYAML\*(Aq;
.Ve
.PP
Or in config.yml or environments/$env.yml
.PP
.Vb 1
\&    session: "YAML"
.Ve
.PP
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.
.PP
See \*(L"Configuration\*(R" in Dancer::Session::Abstract for more configuration options.
.SS "Route Handlers"
.IX Subsection "Route Handlers"
When enabled, the session engine can be used in a route handler with the keyword
\&\fBsession\fR. This keyword allows you to store/retrieve values from the session by
name.
.PP
Storing a value into the session:
.PP
.Vb 1
\&    session foo => \*(Aqbar\*(Aq;
.Ve
.PP
Retrieving that value later:
.PP
.Vb 1
\&    my $foo = session \*(Aqfoo\*(Aq;
.Ve
.PP
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 \f(CW\*(C`/login\*(C'\fR
and \f(CW\*(C`/home\*(C'\fR actions using the session engine.
.PP
.Vb 7
\&    post \*(Aq/login\*(Aq => sub {
\&        # look for params and authenticate the user
\&        # ...
\&        if ($user) {
\&            session user_id => $user\->id;
\&        }
\&    };
\&
\&    get \*(Aq/home\*(Aq => sub {
\&        # if a user is present in the session, let him go, otherwise redirect to
\&        # /login
\&        if (not session(\*(Aquser_id\*(Aq)) {
\&            redirect \*(Aq/login\*(Aq;
\&        }
\&    };
.Ve
.PP
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.
.SH "SUPPORTED ENGINES"
.IX Header "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.
.PP
The following engines are supported out-of-the-box (shipped with the core Dancer
distribution):
.IP "Dancer::Session::YAML" 4
.IX Item "Dancer::Session::YAML"
A \s-1YAML\s0 file-based session backend, pretty convenient for development purposes,
but maybe not the best for production needs.
.IP "Dancer::Session::Simple" 4
.IX Item "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.
.PP
Additionally, many more session engines are available from \s-1CPAN,\s0 including:
.IP "Dancer::Session::Memcached" 4
.IX Item "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.
.IP "Dancer::Session::Cookie" 4
.IX Item "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).
.IP "Dancer::Session::Storable" 4
.IX Item "Dancer::Session::Storable"
This backend stores sessions on disc using Storable, which offers solid
performance and reliable serialization of various data structures.
.IP "Dancer::Session::MongoDB" 4
.IX Item "Dancer::Session::MongoDB"
A backend to store sessions using MongoDB
.IP "Dancer::Session::KiokuDB" 4
.IX Item "Dancer::Session::KiokuDB"
A backend to store sessions using KiokuDB
.IP "Dancer::Session::PSGI" 4
.IX Item "Dancer::Session::PSGI"
Let Plack::Middleware::Session handle sessions; may be useful to share sessions
between a Dancer app and other Plack-based apps.
.SH "DEPENDENCY"
.IX Header "DEPENDENCY"
Dancer::Session may depend on third-party modules, depending on the session
engine used. See the session engine module for details.
.SH "AUTHORS"
.IX Header "AUTHORS"
This module has been written by Alexis Sukrieh. See the \s-1AUTHORS\s0 file that comes
with this distribution for details.
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software and is released under the same terms as Perl
itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See Dancer for details about the complete framework.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 by Alexis Sukrieh.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.