.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
.\"
.\" 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 "User::Simple 3pm"
.TH User::Simple 3pm "2022-06-28" "perl v5.34.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"
User::Simple \- Simple user sessions management
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  $usr = User::Simple\->new(db => $db,
\&                           [tbl => $user_table],
\&                           [durat => $duration],
\&                           [debug => $debug]);
\&
\&  $ok = $usr\->ck_session($session);
\&  $ok = $usr\->ck_login($login, $passwd, [$no_sess]);
\&  $ok = $usr\->set_passwd($new_pass);
\&  $usr\->end_session;
\&
\&  $id = $usr\->id;
\&  $session = $usr\->session;
\&
\&  $otherattrib = $user\->otherattrib
\&  $ok = $user\->set_otherattrib($value);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
User::Simple provides a very simple framework for validating users,
managing their sessions and storing a minimal set of information (this
is, a meaningful user login/password pair, and privilege level) via a database,
while providing a transparent way to access any other attributes you might
define. The sessions can be used as identifiers for i.e. cookies on a Web 
system. The passwords are stored as \s-1MD5\s0 hashes (this means, the password is 
never stored in clear text).
.PP
User::Simple was originally developed with a PostgreSQL database in
mind, but should work with any real \s-1DBMS.\s0 Sadly, this rules out \s-1DBD::CSV,\s0
DBD::XBase, DBD::Excel and many other implementations based on SQL::Statement \-
The user table requires the driver to implement primary keys and 
\&\s-1NOT NULL/UNIQUE\s0 constraints.
.PP
The functionality is split into two modules, User::Simple and 
User::Simple::Admin. This module provides the functionality your system
will need for any interaction started by the user \- Authentication, session
management, querying the user's data, changing the password and changing any
attributes you define not beginning with \f(CW\*(C`adm_\*(C'\fR. Note that you cannot directly
modify a user's login, session or session expiry from within this module \- Just
as a general principle, avoid changing logins. If you absolutely must, use 
User::Simple::Admin instead ;\-)
.SS "\s-1CONSTRUCTOR\s0"
.IX Subsection "CONSTRUCTOR"
In order to create a User::Simple object, call the new argument with an
active \s-1DBI\s0 (database connection) object as its only argument:
.PP
.Vb 2
\&  $usr = User::Simple\->new(db => $db, [tbl => $table], [durat => $duration],
\&                           [debug => $debug]);
.Ve
.PP
Of course, the database must have the right structure in it \- please check
User::Simple::Admin for more information.
.PP
The \f(CW\*(C`tbl\*(C'\fR parameter is the name of the table where the user information is 
stored. If not specified, it defaults to 'user_simple'.
.PP
\&\f(CW\*(C`durat\*(C'\fR is the number of minutes a user's session should last. Its default is
of 30 minutes.
.PP
\&\f(CW\*(C`debug\*(C'\fR is the verbosity level of the debugging messages \- The default is 2, 
it accepts integers between 0 and 5 (higher means more messages). Messages of 
high relevance (i.e. the database failing to reflect any changes we request it
to make) are shown if debug is >= 1, regular failure messages are shown if 
debug >= 3, absolutely everything is shown if debug == 5. Be warned that when
debug is set to 5, information such as cleartext passwords will be logged as 
well!
.SS "\s-1SESSION CREATION/DELETION\s0"
.IX Subsection "SESSION CREATION/DELETION"
Once the object is created, we can ask it to verify that a given user is
valid, either by checking against a session string or against a login/password
pair:
.PP
.Vb 2
\&  $ok = $usr\->ck_session($session);
\&  $ok = $usr\->ck_login($login, $passwd, [$no_sess]);
.Ve
.PP
The optional \f(CW$no_sess\fR argument should be used if we do not want to modify the
current session (or to create a new session), we want only to verify the
password matches (i.e. when asking for the current password as a confirmation 
in order to change a user's password). It will almost always be left false.
.PP
To end a session:
.PP
.Vb 1
\&  $ok = $usr\->end_session;
.Ve
.PP
To verify whether we have successfully validated a user:
.PP
.Vb 1
\&  $ok = $usr\->is_valid;
.Ve
.SS "\s-1QUERYING THE CURRENT USER\s0'S \s-1DATA\s0"
.IX Subsection "QUERYING THE CURRENT USER'S DATA"
To check the user's core attributes (login and \s-1ID\s0):
.PP
.Vb 2
\&  $login = $usr\->login;
\&  $id = $usr\->id;
.Ve
.PP
You might add extra columns to the User::Simple table in your database \- You
will still be able to query for them in the same way:
.PP
.Vb 1
\&  $otherattrib = $user\->otherattrib;
.Ve
.PP
i.e.:
.PP
.Vb 2
\&  $name = $user\->name
\&  $login = $usr\->login;
.Ve
.PP
Note that 'name' and 'level' were core attributes until User::Simple version 
1.0 \- In order to keep User::Simple as simple and extensible as possible, they
became extended attributes. You should not have to modify your code using 
\&\f(CW\*(C`User::Simple\*(C'\fR anyway, as changes are transparent. Some minor \s-1API\s0 changes do 
happen in \f(CW\*(C`User::Simple::Admin\*(C'\fR, though.
.PP
Extended attributes are not checked in any way by User::Simple, they are just 
stored in the database just as they are received \- Some DBDs might not even
verify they are of the correct data type. As always, if you want to ensure
consistence, use a real \s-1RDBMS.\s0
.PP
Of course, beware: if the field does not exist, User::Simple will raise an 
error and die just as if an unknown method had been called.
.PP
To change the user's password:
.PP
.Vb 1
\&  $ok = $usr\->set_passwd($new_pass);
.Ve
.PP
Note that an empty password will not be accepted.
.PP
To change any attribute defined by you and not labeled as for administrative
use (this is, its name does not start with \f(CW\*(C`adm_\*(C'\fR):
.PP
.Vb 1
\&  $ok = $usr\->set_otherattrib($new_value);
.Ve
.SH "DEPENDS ON"
.IX Header "DEPENDS ON"
Date::Calc
.PP
Digest::MD5
.PP
\&\s-1DBI\s0 (and a suitable \s-1DBD\s0 backend)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
User::Simple::Admin for administrative routines
.SH "AUTHOR"
.IX Header "AUTHOR"
Gunnar Wolf <gwolf@gwolf.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2005\-2009 Gunnar Wolf / Instituto de Investigaciones
Econo\*'micas \s-1UNAM\s0
.PP
This module is Free Software; it can be redistributed under the same
terms as Perl.