.\" 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::Admin 3pm"
.TH User::Simple::Admin 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::Admin \- User::Simple user administration
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  $ua = User::Simple::Admin\->new($db, $user_table);
\&
\&  $ua = User::Simple::Admin\->create_rdbms_db_structure($db, $user_table,
\&      [$extra_sql]);
\&  $ua = User::Simple::Admin\->create_plain_db_structure($db, $user_table,
\&      [$extra_sql]);
\&  $ok = User::Simple::Admin\->has_db_structure($db, $user_table);
\&
\&  %users = $ua\->dump_users;
\&
\&  $id = $ua\->id($login);
\&  $login = $ua\->login($id);
\&
\&  $otherattrib = $user\->otherattrib($id);
\&
\&  $ok = $usr\->set_login($id, $login);
\&  $ok = $usr\->set_passwd($id, $passwd);
\&  $ok = $usr\->set_otherattrib($id, $value);
\&  $ok = $usr\->clear_session($id);
\&
\&  $id = $ua\->new_user(login => $login, passwd => $passwd, 
\&        [otherattribute => $otherattribute]);
\&
\&  $ok = $ua\->remove_user($id);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
User::Simple::Admin manages the administrative part of the User::Simple
modules \- Please check User::Simple for a general overview of these modules
and an explanation on what-goes-where.
.PP
User::Simple::Admin works as a regular administrator would: The module should
be instantiated only once for all of your users' administration, if possible,
and not instantiated once for each user (in contraposition to User::Simple,
as it works from each of the users' perspective in independent instantiations).
.PP
Note also that User::Simple::Admin does b<not> perform the administrative user
checks \- It is meant to be integrated to your system, and it is your system 
which should carry out all of the needed authentication checks.
.SS "\s-1CONSTRUCTOR\s0"
.IX Subsection "CONSTRUCTOR"
Administrative actions for User::Simple modules are handled through this
Admin object. To instantiate it:
.PP
.Vb 1
\&  $ua = User::Simple::Admin\->new($db, $user_table);
.Ve
.PP
\&\f(CW$db\fR is an open connection to the database where the user data is stored.
.PP
\&\f(CW$user_table\fR is the name of the table that holds the users' data.
.PP
If we do not yet have the needed \s-1DB\s0 structure to store the user information,
we can use this class method as a constructor as well:
.PP
.Vb 2
\&  $ua = User::Simple::Admin\->create_rdbms_db_structure($db, $user_table,
\&      [$extra_sql]);
\&
\&  $ua = User::Simple::Admin\->create_plain_db_structure($db, $user_table,
\&      [$extra_sql]);
.Ve
.PP
The first one should be used if your \s-1DBI\s0 handle ($db) points to a real \s-1RDBMS,\s0
such as PostgreSQL or MySQL. In case you are using a file-based \s-1DBD\s0 (such as
DBD::XBase, \s-1DBD::DBM, DBD::CVS\s0 or any other which does not use a real \s-1RDBMS\s0
for storage), use \f(CW\*(C`User::Simple::Admin\->create_plain_db_structure\*(C'\fR
instead. What is the difference? In the first case, we will create a table
that has internal consistency checks \- Some fields are declared \s-1NOT NULL,\s0 some
fields are declared \s-1UNIQUE,\s0 and the user \s-1ID\s0 is used as a \s-1PRIMARY KEY.\s0 This 
cannot, of course, be achieved using file-based structures, so the integrity
can only be maintained from within our scripts.
.PP
This module does not provide the functionality to modify the created tables
by adding columns to it, although methods do exist to access and modify the
values stored in those columns (see the \*(L"\s-1CREATING, QUERYING AND MODIFYING
USERS\*(R"\s0 section below), as many DBDs do not implement the \s-1ALTER TABLE SQL\s0 
commands. It does, however, allow you to specify extra fields in the tables at
creation time \- If you specify a third extra parameter, it will be included as 
part of the table creation \- i.e., you can create a User::Simple table with
fields for the user's first and family names and a \s-1UNIQUE\s0 constraint over
them this way:
.PP
.Vb 3
\&  $ua = User::Simple::Admin\->create_rdbms_db_structure($db, $user_table,
\&      \*(Aqfirstname varchar(30) NOT NULL, famname varchar(30) NOT NULL,
\&       UNIQUE (firstname,famname)\*(Aq);
.Ve
.PP
Keep in mind that the internal fields are \f(CW\*(C`id\*(C'\fR, \f(CW\*(C`login\*(C'\fR, \f(CW\*(C`passwd\*(C'\fR, 
\&\f(CW\*(C`session\*(C'\fR and \f(CW\*(C`session_exp\*(C'\fR. Don't mess with them ;\-) Avoid adding any fields
starting with \f(CW\*(C`set_\*(C'\fR or called as any method defined here, as they will 
become unreachable. And, of course, keep in mind what \s-1SQL\s0 construct does your 
\&\s-1DBD\s0 support.
.PP
If you add any fields with names starting with \f(CW\*(C`adm_\*(C'\fR, they will be visible 
but not modifiable from within User::Simple \- You will only be able to
modify them from User::Simple::Admin.
.SS "\s-1QUERYING FOR DATABASE READINESS\s0"
.IX Subsection "QUERYING FOR DATABASE READINESS"
In order to check if the database is ready to be used by this module with the
specified table name, use the \f(CW\*(C`has_db_structure\*(C'\fR class method:
.PP
.Vb 1
\&  $ok = User::Simple::Admin\->has_db_structure($db, $user_table);
.Ve
.SS "\s-1RETRIEVING THE SET OF USERS\s0"
.IX Subsection "RETRIEVING THE SET OF USERS"
.Vb 1
\&  %users = $ua\->dump_users;
.Ve
.PP
Will return a hash with the data regarding the registered users with all of the
existing \s-1DB\s0 fields, in the following form:
.PP
.Vb 3
\&  ( $id1 => { login=>$login1, firstname=>$firstname1, famname=>$famname1 },
\&    $id2 => { login=>$login2, firstname=>$firstname2, famname=>$famname2 },
\&    (...) )
.Ve
.PP
Of course, with the appropriate attributes. The internal attributes \f(CW\*(C`id\*(C'\fR, 
\&\f(CW\*(C`session\*(C'\fR and \f(CW\*(C`session_exp\*(C'\fR will not be included in the resulting hashes (you
have the \f(CW\*(C`id\*(C'\fR as the hash keys).
.SS "\s-1CREATING, QUERYING AND MODIFYING USERS\s0"
.IX Subsection "CREATING, QUERYING AND MODIFYING USERS"
.Vb 2
\&  $id = $ua\->new_user(login => $login, passwd => $passwd, 
\&        [otherattribute => $otherattribute]);
.Ve
.PP
Creates a new user with the specified data. Returns the new user's \s-1ID.\s0 Only
the login is mandatory (as it uniquely identifies the user), unless you have
specified extra \s-1NOT NULL\s0 fields or constraints in the \s-1DB.\s0 If no password is 
supplied, the account will be created, but no login will be allowed until one 
is supplied.
.PP
.Vb 1
\&  $ok = $ua\->remove_user($id);
.Ve
.PP
Removes the user specified by the \s-1ID.\s0
.PP
.Vb 2
\&  $id = $ua\->id($login);
\&  $login = $ua\->login($id);
\&
\&  $otherattrib = $user\->otherattrib($id);
.Ve
.PP
Get the value of each of the mentioned attributes. Note that in order to get
the \s-1ID\s0 you can supply the login, every other method answers only to the \s-1ID.\s0 In
case you have the login and want to get the firstname, you can use 
\&\f(CW\*(C`$ua\-\*(C'\fRfirstname($ua\->id($login));>
.PP
Of course, beware: if you request for a field which does not exist in your
table, User::Simple will raise an  error and die just as if an unknown method 
had been called.
.PP
.Vb 2
\&  $ok = $usr\->set_login($id, $login);
\&  $ok = $usr\->set_passwd($id, $passwd);
.Ve
.PP
Modifies the requested attribute of the specified user, setting it to the new 
value. Except for the login, they can all be set to null values \- If the 
password is set to a null or empty value, the account will be locked (that is, 
no password will be accepted). The internal attributes \f(CW\*(C`id\*(C'\fR, \f(CW\*(C`session\*(C'\fR and 
\&\f(CW\*(C`session_exp\*(C'\fR cannot be directly modified (you have the \f(CW\*(C`id\*(C'\fR as the hash 
keys).
.PP
Just as with the accessors, if you have extra columns, you can modify them the
same way:
.PP
.Vb 1
\&  $ok = $usr\->set_otherattrib($id, $value);
.Ve
.PP
i.e.
.PP
.Vb 1
\&  $ok = $usr\->set_name($id, $name);
.Ve
.SS "\s-1SESSIONS\s0"
.IX Subsection "SESSIONS"
.Vb 1
\&  $ok = $usr\->clear_session($id);
.Ve
.PP
Removes the session which the current user had open, if any.
.PP
Note that you cannot create a new session through this module \- The only way of
creating a session is through the \f(CW\*(C`ck_login\*(C'\fR method of User::Simple.
.SH "DEPENDS ON"
.IX Header "DEPENDS ON"
Digest::MD5
.SH "SEE ALSO"
.IX Header "SEE ALSO"
User::Simple for the regular user authentication routines (that is, to
use the functionality this module adimisters)
.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.