NAME

User::Simple - Simple user sessions management

SYNOPSIS

$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;

$name = $usr->name;
$login = $usr->login;
$id = $usr->id;
$session = $usr->session;
$level = $usr->level;

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, the user's name and privilege level) via a database. The sessions can be used as identifiers for i.e. cookies on a Web system. The passwords are stored as MD5 hashes (this means, the password is never stored in clear text).

User::Simple was originally developed with a PostgreSQL database in mind, but should work with any real DBMS. Sadly, this rules out DBD::CSV, DBD::XBase, DBD::Excel and many other implementations based on SQL::Statement - The user table requires the driver to implement primary keys and NOT NULL/UNIQUE constraints.

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 and changing the password. Any other changes (i.e., changing the user's name, login or level) should be carried out using User::Simple::Admin.

CONSTRUCTOR

In order to create a User::Simple object, call the new argument with an active DBI (database connection) object as its only argument:

$usr = User::Simple->new(db => $db, [tbl => $table], [durat => $duration],
                         [debug => $debug]);

Of course, the database must have the right structure in it - please check User::Simple::Admin for more information.

The tbl parameter is the name of the table where the user information is stored. If not specified, it defaults to 'user_simple'.

durat is the number of minutes a user's session should last. Its default is of 30 minutes.

debug 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!

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::

$ok = $usr->ck_session($session);
$ok = $usr->ck_login($login, $passwd, [$no_sess]);

The optional $no_sess 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.

To end a session:

$ok = $usr->end_session;

To verify whether we have successfully validated a user:

$ok = $usr->is_valid;

QUERYING THE CURRENT USER'S DATA

To check the user's attributes (name, login and ID):

$name = $usr->name;
$login = $usr->login;
$id = $usr->id;

To change the user's password:

$ok = $usr->set_passwd($new_pass);

USER LEVEL

To check for the user level (again, see User::Simple::Admin for further details):

$level = $usr->level;

DEPENDS ON

Date::Calc

Digest::MD5

DBI (and a suitable DBD backend)

SEE ALSO

User::Simple::Admin for administrative routines

TO DO

I would like to separate a bit the table structure, allowing for flexibility - This means, if you added some extra fields to the table, provide an easy way to access them. Currently, you have to reach in from outside User::Simple, skipping the abstraction, to get them.

Although no longer documented (don't use them, please!), we still have the adm_level/is_admin functionality. For cleanness, it should be removed by the next release.

Besides that, it works as expected (that is, as I expect ;-) )

AUTHOR

Gunnar Wolf <gwolf@gwolf.org>

COPYRIGHT

Copyright 2005 Gunnar Wolf / Instituto de Investigaciones Económicas UNAM This module is Free Software, it can be redistributed under the same terms as Perl.