.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Catalyst::Plugin::Session::Store 3pm"
.TH Catalyst::Plugin::Session::Store 3pm "2018-12-22" "perl v5.28.1" "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"
Catalyst::Plugin::Session::Store \- Base class for session storage
drivers.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    package Catalyst::Plugin::Session::Store::MyBackend;
\&    use base qw/Catalyst::Plugin::Session::Store/;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class doesn't actually provide any functionality, but when the
\&\f(CW\*(C`Catalyst::Plugin::Session\*(C'\fR module sets up it will check to see that
\&\f(CW\*(C`YourApp\->isa("Catalyst::Plugin::Session::Store")\*(C'\fR. When you write
a session storage plugin you should subclass this module for this
reason. This documentation is intended for authors of session storage 
plugins, not for end users.
.SH "WRITING STORE PLUGINS"
.IX Header "WRITING STORE PLUGINS"
All session storage plugins need to adhere to the following interface
specification to work correctly:
.SS "Required Methods"
.IX Subsection "Required Methods"
.ie n .IP "get_session_data $key" 4
.el .IP "get_session_data \f(CW$key\fR" 4
.IX Item "get_session_data $key"
.PD 0
.ie n .IP "store_session_data $key, $data" 4
.el .IP "store_session_data \f(CW$key\fR, \f(CW$data\fR" 4
.IX Item "store_session_data $key, $data"
.PD
Retrieve or store session data by key.
.Sp
\&\f(CW$data\fR is currently either a hash reference (for most keys) or an
integer value (for expires), but all value types should be supported.
.Sp
Keys are in the format \f(CW\*(C`prefix:id\*(C'\fR, where \f(CW\*(C`prefix\*(C'\fR is \f(CW\*(C`session\*(C'\fR,
\&\f(CW\*(C`expires\*(C'\fR, or \f(CW\*(C`flash\*(C'\fR, and \f(CW\*(C`id\*(C'\fR is always the session \s-1ID.\s0 Plugins
such as Catalyst::Plugin::Session::PerUser store extensions to this
format, such as \f(CW\*(C`user:username\*(C'\fR.
.Sp
It is suggested that the store should split on the colon and store the
data more efficiently \- the \s-1API\s0 should remain stable, with the possible
addition of new prefixes in the future.
.Sp
For example, \f(CW\*(C`Store::DBI\*(C'\fR maps \f(CW\*(C`expires:id\*(C'\fR a column of \f(CW\*(C`session:id\*(C'\fR
by special-casing \f(CW\*(C`get_session_data\*(C'\fR and \f(CW\*(C`store_session_data\*(C'\fR for that
key format, in order to ease the implementation of
\&\f(CW\*(C`delete_expired_sessions\*(C'\fR.
.Sp
The only assurance stores are required to make is that given
.Sp
.Vb 1
\&    $c\->store_session_data( $x, $y );
.Ve
.Sp
for any \f(CW$x\fR,
.Sp
.Vb 1
\&    $y == $c\->get_session_data( $x )
.Ve
.Sp
will hold.
.ie n .IP "store_session_data ( $key, $data )" 4
.el .IP "store_session_data ( \f(CW$key\fR, \f(CW$data\fR )" 4
.IX Item "store_session_data ( $key, $data )"
Store a session whose \s-1KEY\s0 is the first parameter and data is the second
parameter in storage.
.Sp
The second parameter is a hash reference, which should normally be
serialized (and later deserialized by \f(CW\*(C`get_session_data\*(C'\fR).
.ie n .IP "delete_session_data ( $key )" 4
.el .IP "delete_session_data ( \f(CW$key\fR )" 4
.IX Item "delete_session_data ( $key )"
Delete the session whose \s-1KEY\s0 is the parameter.
.IP "delete_expired_sessions" 4
.IX Item "delete_expired_sessions"
This method is not called by any code at present, but may be called in the
future, as part of a Catalyst-specific maintenance script.
.Sp
If you are wrapping around a backend which manages its own auto expiry
you can just give this method an empty body.
.SS "Error handling"
.IX Subsection "Error handling"
All errors should be thrown using Catalyst::Exception. Return values
are not checked, and are assumed to be \s-1OK.\s0 Missing values are not errors.
.SS "Auto-Expiry on the Backend"
.IX Subsection "Auto-Expiry on the Backend"
Storage plugins are encouraged to use \f(CW\*(C`$c\->session_expires\*(C'\fR, \f(CW\*(C`$c\->config(\*(AqPlugin::Session\*(Aq => { expires => $val })\*(C'\fR, or the storage of the
\&\f(CW\*(C`expires:$sessionid\*(C'\fR key to perform more efficient expiration, but only
for the key prefixes \f(CW\*(C`session\*(C'\fR, \f(CW\*(C`flash\*(C'\fR and \f(CW\*(C`expires\*(C'\fR.
.PP
If the backend chooses not to do so, Catalyst::Plugin::Session will
detect expired sessions as they are retrieved and delete them if
necessary.
.PP
Note that session store that use this approach may leak disk space,
since nothing will actively delete an expired session. The
\&\f(CW\*(C`delete_expired_sessions\*(C'\fR method is there so that regularly scheduled
maintenance scripts can give your backend the opportunity to clean up.
.SS "Early Finalization"
.IX Subsection "Early Finalization"
By default the main session plugin will finalize during body finalization
which ensures that all controller code related to the session has completed.
However some storage plugins may wish to finalize earlier, during header
finalization.  For example a storage that saved state in a client cookie
would wish this.  If a storage plugin wants to finalize early it should set
\&\f(CW$c\fR\->_needs_early_session_finalization to true.  Please note that if you
do this in a storage plugin, you should warn users not to attempt to change
or add session keys if you use a streaming or socket interface such as
\&\f(CW$c\fR\->res\->write, \f(CW$c\fR\->res\->write_fh or \f(CW$c\fR\->req\->io_fh.