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.