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
         $ok = $user->set_otherattrib($value);

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, changing the password
       and changing any attributes you define not beginning with "adm_". 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 ;-)

   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.

       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 RDBMS.

       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.

       To change any attribute defined by you and not labeled as for administrative use (this is,
       its name does not start with "adm_"):

         $ok = $usr->set_otherattrib($new_value);

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-2009 Gunnar Wolf / Instituto de Investigaciones Economicas UNAM

       This module is Free Software; it can be redistributed under the same terms as Perl.