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;

  $id = $usr->id;
  $session = $usr->session;

  $otherattrib = $user->otherattrib

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 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 login, level or any attributes you define) 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 core attributes (login and ID):

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

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:

  $otherattrib = $user->otherattrib;

i.e.:

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

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 User::Simple anyway, as changes are transparent. Some minor API changes do happen in User::Simple::Admin, though.

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.

To change the user's password:

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

Note that an empty password will not be accepted.

DEPENDS ON

Date::Calc

Digest::MD5

DBI (and a suitable DBD backend)

SEE ALSO

User::Simple::Admin for administrative routines

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.