.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "Data::Session::CGISession 3pm"
.TH Data::Session::CGISession 3pm "2023-02-14" "perl v5.36.0" "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"
Data::Session \- A persistent session manager
.SH "The Design of Data::Session, contrasted with CGI::Session"
.IX Header "The Design of Data::Session, contrasted with CGI::Session"
For background, read the docs (including the Changes files) and bug reports for both
Apache::Session and CGI::Session.
.PP
The interface to Data::Session is not quite compatible with that of CGI::Session, hence the
new namespace.
.PP
The purpose of Data::Session is to be a brand-new alternative to both Apache::Session and
CGI::Session.
.SH "Aliases for Method Names"
.IX Header "Aliases for Method Names"
Aliases for method names are not supported.
.PP
In CGI::Session, methods \fBetime()\fR and \fBexpires()\fR were aliased to \fBexpire()\fR. This is not supported
in Data::Session.
.PP
Data::Session does have an \fBetime()\fR method, \*(L"Method: \fBetime()\fR\*(R" in Data::Session, which is different.
.PP
In CGI::Session, method \fBheader()\fR was aliased to \fBhttp_header()\fR. Only the latter method is
supported in Data::Session. See \*(L"Method: \fBcookie()\fR\*(R" and \*(L"Method: http_header([@arg])\*(R".
.PP
In CGI::Session, id generators had a method \fBgenerate_id()\fR aliased to \fBgenerate()\fR. This is not
supported in Data::Session.
.PP
In CGI::Session, method \fBparam_dataref()\fR was aliased to \fBdataref()\fR. Neither of these methods is
supported in Data::Session. If you want to access the session data, use
my($hashref) = \f(CW$session\fR \-> session.
.SH "Backwards-compatibility"
.IX Header "Backwards-compatibility"
This topic is sometimes used as a form of coercion, which is unacceptable, and sometimes leads to
a crippled design.
.PP
So, by design, Data::Session is not \fIexactly\fR backwards-compatible with CGI::Session, but
does retain it's major features:
.ie n .IP "o Specify the basic operating parameters with new(type => $string)" 4
.el .IP "o Specify the basic operating parameters with new(type => \f(CW$string\fR)" 4
.IX Item "o Specify the basic operating parameters with new(type => $string)"
This determines the type of session object you wish to create.
.Sp
Default: 'driver:File;id:MD5;serialize:DataDumper'.
.Sp
And specifically, the format of that case-sensitive string is as expected. See
\&\*(L"Specifying Session Options\*(R" in Data::Session for details.
.IP "o Retrieve the session id with the \fBid()\fR method" 4
.IX Item "o Retrieve the session id with the id() method"
.PD 0
.IP "o Set and get parameters with the \fBparam()\fR method" 4
.IX Item "o Set and get parameters with the param() method"
.IP "o Ensure session data is saved to disk with the \fBflush()\fR method" 4
.IX Item "o Ensure session data is saved to disk with the flush() method"
.PD
Call this just before your program exits.
.Sp
In particular, as with CGI::Session, persistent environments stop your program exiting in the way
you are used to. This matter is discussed in \*(L"Trouble with Exiting\*(R" in Data::Session.
.SH "CGI::Session::ExpireSessions is obsolete"
.IX Header "CGI::Session::ExpireSessions is obsolete"
Instead, consider using scripts/expire.pl, which ships with Data::Session.
.SH "Code refs as database handles"
.IX Header "Code refs as database handles"
Being able to supply a code ref as the value of the 'dbh' parameter to \fBnew()\fR is supported.
.PP
This mechanism is used to delay creation of a database handle until it is actually needed,
which means if it is not needed it is not created.
.SH "Class 'v' Object"
.IX Header "Class 'v' Object"
Calling methods on the class is not supported. You must always create an object.
.PP
The reason for this is to ensure every method call, without exception, has access to the per-object
data supplied by you, or by default, in the call to \fBnew()\fR.
.SH "The type of the Data::Session object"
.IX Header "The type of the Data::Session object"
Controlling the capabilities of the Data::Session object is determined by the 'type' parameter
passed in to new, as Data::Session \-> new(type => \f(CW$string\fR).
.PP
A sample string looks like 'driver:BerkeleyDB;id:SHA1;serialize:DataDumper'.
.PP
Abbreviation of component key names ('driver', 'id', 'serialize') is not supported.
.PP
Such abbreviations were previously handled by Text::Abbrev. Now, these must be named in full.
.PP
The decision to force corresponding class names to lower case is not supported.
.PP
Nevertheless, lower-cased input will be accepted. Such input is converted to the case you expect.
.PP
This affects the names of various sub-classes. See \*(L"\s-1ID\s0 Generators\*(R", \*(L"Serialization Drivers\*(R" and
\&\*(L"Storage Drivers\*(R".
.PP
For example, driver:pg is now driver:Pg, which actually means Data::Session::Driver::Pg, based on
the class name DBD::Pg.
.SH "Exceptions"
.IX Header "Exceptions"
Exceptions are caught with Try::Tiny. Errors cause Data::Session to die.
.PP
The only exception to this is the call to \fBnew()\fR, which can return undef. In that case, check
\&\f(CW$Data::Session::errstr\fR.
.SH "Global Variables"
.IX Header "Global Variables"
Global variables are not supported. This includes:
.ie n .IP "o $CGI::Session::Driver::DBI::TABLE_NAME" 4
.el .IP "o \f(CW$CGI::Session::Driver::DBI::TABLE_NAME\fR" 4
.IX Item "o $CGI::Session::Driver::DBI::TABLE_NAME"
.PD 0
.ie n .IP "o $CGI::Session::Driver::DBI::*::TABLE_NAME" 4
.el .IP "o \f(CW$CGI::Session::Driver::DBI::\fR*::TABLE_NAME" 4
.IX Item "o $CGI::Session::Driver::DBI::*::TABLE_NAME"
.ie n .IP "o $CGI::Session::Driver::file::FileName" 4
.el .IP "o \f(CW$CGI::Session::Driver::file::FileName\fR" 4
.IX Item "o $CGI::Session::Driver::file::FileName"
.ie n .IP "o $CGI::Session::IP_MATCH" 4
.el .IP "o \f(CW$CGI::Session::IP_MATCH\fR" 4
.IX Item "o $CGI::Session::IP_MATCH"
.ie n .IP "o $CGI::Session::NAME" 4
.el .IP "o \f(CW$CGI::Session::NAME\fR" 4
.IX Item "o $CGI::Session::NAME"
.PD
.SH "ID Generators"
.IX Header "ID Generators"
Id generator classes have been renamed:
.IP "o CGI::Session::ID::incr becomes Data::Session::ID::AutoIncrement" 4
.IX Item "o CGI::Session::ID::incr becomes Data::Session::ID::AutoIncrement"
.PD 0
.IP "o CGI::Session::ID::md5 becomes Data::Session::ID::MD5" 4
.IX Item "o CGI::Session::ID::md5 becomes Data::Session::ID::MD5"
.IP "o CGI::Session::ID::sha becomes Data::Session::ID::SHA1" 4
.IX Item "o CGI::Session::ID::sha becomes Data::Session::ID::SHA1"
.IP "o CGI::Session::ID::sha256 becomes Data::Session::ID::SHA256" 4
.IX Item "o CGI::Session::ID::sha256 becomes Data::Session::ID::SHA256"
.IP "o CGI::Session::ID::sha512 becomes Data::Session::ID::SHA512" 4
.IX Item "o CGI::Session::ID::sha512 becomes Data::Session::ID::SHA512"
.IP "o CGI::Session::ID::static becomes Data::Session::ID::Static" 4
.IX Item "o CGI::Session::ID::static becomes Data::Session::ID::Static"
.IP "o CGI::Session::ID::uuid becomes Data::Session::ID::UUID16 or \s-1UUID34\s0 or \s-1UUID36\s0 or \s-1UUD64\s0" 4
.IX Item "o CGI::Session::ID::uuid becomes Data::Session::ID::UUID16 or UUID34 or UUID36 or UUD64"
.PD
.SH "JSON"
.IX Header "JSON"
Data::Session::Serialize::JSON uses \s-1JSON\s0, not JSON::Syck.
.SS "Managing Object Attributes"
.IX Subsection "Managing Object Attributes"
The light-weight Hash::FieldHash is used to manage object attributes.
.PP
So, neither Mouse nor Moose, nor any other such class helper, is used.
.SH "Method: \fBcookie()\fP"
.IX Header "Method: cookie()"
Forcing the query object to have a cookie method is not supported. You may now use a query class
which does not provide a cookie method.
.PP
The logic of checking the cookie (if any) first (i.e. before checking for a form field of the same
name) is supported.
.PP
See \*(L"Method: http_header([@arg])\*(R".
.SH "Method: http_header([@arg])"
.IX Header "Method: http_header([@arg])"
The [] indicate an optional parameter.
.PP
Returns a \s-1HTTP\s0 header. This means it does not print the header. You have to do that, when
appropriate.
.PP
Forcing the document type to be 'text/html' when calling \fBhttp_header()\fR is not supported. You must
pass in a document type to \fBhttp_header()\fR, as \f(CW$session\fR \-> http_header('\-type' => 'text/html'), or
use the query object's default. Both \s-1CGI\s0 and CGI::Simple default to 'text/html'.
.PP
Data::Session handles the case where the query object does not have a \fBcookie()\fR method.
.PP
The \f(CW@arg\fR parameter, if any, is passed to the query object's \fBheader()\fR method, after the cookie
parameter, if any.
.SH "Method: \fBload()\fP"
.IX Header "Method: load()"
The new \fBload()\fR takes no parameters.
.SH "Method: \fBnew()\fP"
.IX Header "Method: new()"
Excess versions of \fBnew()\fR are not supported.
.PP
The new \fBnew()\fR takes a hash of parameters.
.PP
This hash will include all options previously passed in in different parameters to \fBnew()\fR, including
\&\f(CW$dsn\fR, \f(CW$query\fR, \f(CW$sid\fR, \e%dsn_args and \e%session_params.
.SH "Name Changes"
.IX Header "Name Changes"
Class name changes are discussed in \*(L"\s-1ID\s0 Generators\*(R", \*(L"Serialization Drivers\*(R" and
\&\*(L"Storage Drivers\*(R".
.PP
As discussed in \*(L"Method: \fBnew()\fR\*(R" in Data::Session, these name changes are both the result of cleaning
up all the options to \fBnew()\fR, and because the option names are now also method names.
.IP "o DataColName becomes data_col_name" 4
.IX Item "o DataColName becomes data_col_name"
This is used in the call to \fBnew()\fR.
.IP "o DataSource becomes data_source" 4
.IX Item "o DataSource becomes data_source"
This is used in the call to \fBnew()\fR.
.IP "o generate_id becomes generate" 4
.IX Item "o generate_id becomes generate"
This is used in various id generator classes, some of which provided generate as an alias.
.IP "o Handle becomes dbh" 4
.IX Item "o Handle becomes dbh"
This is used in the call to \fBnew()\fR.
.IP "o IdColName becomes id_col_name" 4
.IX Item "o IdColName becomes id_col_name"
This is used in the call to \fBnew()\fR.
.IP "o IDFile becomes id_file" 4
.IX Item "o IDFile becomes id_file"
This is used in the call to \fBnew()\fR, and in the '... id:AutoIncrement ...' id generator.
.IP "o IDIncr becomes id_step" 4
.IX Item "o IDIncr becomes id_step"
This is used in the call to \fBnew()\fR, and in the '... id:AutoIncrement ...' id generator.
.IP "o IDInit becomes id_base" 4
.IX Item "o IDInit becomes id_base"
This is used in the call to \fBnew()\fR, and in the '... id:AutoIncrement ...' id generator.
.SH "\fBparam()\fP"
.IX Header "param()"
Excess versions of \fBparam()\fR will not be supported.
.PP
Use param($key => \f(CW$value\fR) to set and param($key) to get.
.PP
\&\fBparam()\fR may be passed a hash, to set several key/value pairs in 1 call.
.SH "POD"
.IX Header "POD"
All \s-1POD\s0 has been re-written.
.SH "Race Conditions"
.IX Header "Race Conditions"
The race handling code in CGI::Session::Driver::postgresql has been incorporated into other
Data::Session::Driver::* drivers.
.SH "Serialization Drivers"
.IX Header "Serialization Drivers"
Serializing classes have been renamed:
.IP "o CGI::Session::Serialize::default becomes Data::Session::Serialize::DataDumper" 4
.IX Item "o CGI::Session::Serialize::default becomes Data::Session::Serialize::DataDumper"
.PD 0
.IP "o CGI::Session::Serialize::freezethaw becomes Data::Session::Serialize::FreezeThaw" 4
.IX Item "o CGI::Session::Serialize::freezethaw becomes Data::Session::Serialize::FreezeThaw"
.IP "o CGI::Session::Serialize::json becomes Data::Session::Serialize::JSON" 4
.IX Item "o CGI::Session::Serialize::json becomes Data::Session::Serialize::JSON"
.PD
The latter will use \s-1JSON\s0. In the past JSON::Syck was used.
.IP "o CGI::Session::Serialize::storable becomes Data::Session::Serialize::Storable" 4
.IX Item "o CGI::Session::Serialize::storable becomes Data::Session::Serialize::Storable"
.PD 0
.IP "o CGI::Session::Serialize::yaml becomes Data::Session::Serialize::YAML" 4
.IX Item "o CGI::Session::Serialize::yaml becomes Data::Session::Serialize::YAML"
.PD
The latter uses YAML::Tiny. In the past either YAML::Syck or \s-1YAML\s0 was used.
.SH "Session ids will be mandatory"
.IX Header "Session ids will be mandatory"
The ability to create a Perl object without a session id is not supported.
.PP
Every time a object of type Data::Session is created, it must have an id.
.PP
This id is either supplied by the caller, taken from the query object, or one is generated.
.PP
See \*(L"Specifying an Id\*(R" in Data::Session for details.
.SH "Session modification"
.IX Header "Session modification"
CGI::Session tracks calls to \fBparam()\fR to set a flag if the object is modified, so as to avoid
writing the session to disk if nothing has been modified.
.PP
This includes checking if setting a param's value to the value it already has.
.PP
The behaviour is supported.
.SH "Session Parameters"
.IX Header "Session Parameters"
CGI::Session had these internal object attributes (parameters) not available to the user:
.IP "o _DATA" 4
.IX Item "o _DATA"
Hashref: Keys: _SESSION_ATIME, _SESSION_CTIME, _SESSION_ID and _SESSION_REMOTE_ADDR.
.IP "o _DSN" 4
.IX Item "o _DSN"
Hashref.
.IP "o _OBJECTS" 4
.IX Item "o _OBJECTS"
Hashref.
.IP "o _DRIVER_ARGS" 4
.IX Item "o _DRIVER_ARGS"
Hashref.
.IP "o _CLAIMED_ID" 4
.IX Item "o _CLAIMED_ID"
Scalar.
.IP "o _STATUS" 4
.IX Item "o _STATUS"
Scalar (bitmap).
.IP "o _QUERY" 4
.IX Item "o _QUERY"
Scalar.
.PP
Data::Session has these internal object attributes (parameters):
.IP "o _SESSION_ATIME" 4
.IX Item "o _SESSION_ATIME"
Scalar: Last access time.
.IP "o _SESSION_CTIME" 4
.IX Item "o _SESSION_CTIME"
Scalar: Creation time.
.IP "o _SESSION_ETIME" 4
.IX Item "o _SESSION_ETIME"
Scalar: Expiry time.
.IP "o _SESSION_ID" 4
.IX Item "o _SESSION_ID"
Scalar: The id.
.IP "o _SESSION_PTIME" 4
.IX Item "o _SESSION_PTIME"
Hashref: Expiry times of parameters.
.PP
Data::Session stores user data internally in a hashref, and the module reserves keys starting
with '_'.
.PP
Of course, it has a whole set of methods to manage state.
.SH "Session States"
.IX Header "Session States"
CGI::Session objects can be one of 6 states. Every attempt has been made to simplify this design.
.SH "Storage Drivers"
.IX Header "Storage Drivers"
Classes related to \s-1DBI/DBD\s0 will use DBD::* style names, to help beginners.
.PP
Hence (with special cases):
.IP "o CGI::Session::Driver::db_file becomes Data::Session::Driver::BerkeleyDB" 4
.IX Item "o CGI::Session::Driver::db_file becomes Data::Session::Driver::BerkeleyDB"
The latter no longer uses DB_File.
.IP "o CGI::Session::Driver::file becomes Data::Session::Driver::File" 4
.IX Item "o CGI::Session::Driver::file becomes Data::Session::Driver::File"
.PD 0
.IP "o CGI::Session::Driver::memcached becomes Data::Session::Driver::Memcached" 4
.IX Item "o CGI::Session::Driver::memcached becomes Data::Session::Driver::Memcached"
.IP "o CGI::Session::Driver::mysql becomes Data::Session::Driver::mysql" 4
.IX Item "o CGI::Session::Driver::mysql becomes Data::Session::Driver::mysql"
.IP "o CGI::Session::Driver::odbc becomes Data::Session::Driver::ODBC" 4
.IX Item "o CGI::Session::Driver::odbc becomes Data::Session::Driver::ODBC"
.IP "o CGI::Session::Driver::oracle becomes Data::Session::Driver::Oracle" 4
.IX Item "o CGI::Session::Driver::oracle becomes Data::Session::Driver::Oracle"
.IP "o CGI::Session::Driver::postgresql becomes Data::Session::Driver::Pg" 4
.IX Item "o CGI::Session::Driver::postgresql becomes Data::Session::Driver::Pg"
.IP "o CGI::Session::Driver::sqlite becomes Data::Session::Driver::SQLite" 4
.IX Item "o CGI::Session::Driver::sqlite becomes Data::Session::Driver::SQLite"
.PD
.SH "Tests"
.IX Header "Tests"
All tests have been re-written.
.SH "The Version of Perl"
.IX Header "The Version of Perl"
Perl 5 code will be used.
.SH "YAML"
.IX Header "YAML"
Data::Session::Serialize::YAML uses YAML::Tiny, not YAML::Syck or \s-1YAML\s0.
.SH "Author"
.IX Header "Author"
Data::Session was written by Ron Savage \fI<ron@savage.net.au>\fR in 2010.
.PP
Home page: <http://savage.net.au/index.html>.
.SH "Copyright"
.IX Header "Copyright"
Australian copyright (c) 2010, Ron Savage.
.PP
.Vb 4
\&        All Programs of mine are \*(AqOSI Certified Open Source Software\*(Aq;
\&        you can redistribute them and/or modify them under the terms of
\&        The Artistic License, a copy of which is available at:
\&        http://www.opensource.org/licenses/index.html
.Ve