Docs » WebApp::User

a user of the web app

NAME

WebApp::User - a user of the web app

VERSION

  Time-stamp: <2006-04-25 14:14:46 mailto:attila@stalphonsos.com>
  $Id: User.pm,v 1.14 2006/04/26 03:52:03 attila Exp $

SYNOPSIS

 use WebApp::User;
 # create new user
 $user = new WebApp::User(dbh => $dbh,
                          CREATE => 1,
                          user => $uid,
                          name => $real_name,
                          email => $user_email,
                          password => $password,
                          class => $user_class);

 # look up user by uid
 $user = new WebApp::User(dbh => $dbh, user => $uid);

 $id       = $user->id();
 $name     = $user->name([$new_name]);
 $email    = $user->email([$new_email]);
 $password = $user->password([$new_password]);
 $class    = $user->class([$new_class]);

 # Not parseable, just for human consumption:
 print STDERR $user->as_string(), "\n";
 # alternatively:
 $user->dump(\*STDERR);

 print "User was freshly created\n"         if $user->is_fresh();
 print "User is nobody (not a real user)\n" if $user->is_nobody();

 # To remove a user from the database
 $user->delete();

 # To store changes back to the database
 $user->store();

 # users have preferences, represented as a hashref of arrayrefs, since
 # each preference can have multiple values (in order).  Sessions use
 # the same representation.

 # To set all of a Users preferences at once, e.g. from the values
 # in the session:
 $user->copy_prefs($hashref);

 # To get all of the Users preferences, e.g. to set in a session:
 $prefs = $user->get_vars();

 # In all cases, $WebApp::User::ERROR has the last error message
 # that any primitive produced

DESCRIPTION

A user identity for the purposes of a particular webapp.

OVERVIEW

WebApp::User objects represent users of a particular webapp, which have their meta-information stored in a DBI database.

There is a special user, called nobody, which should be created in the underlying database if it is intended that the application be usable at all by unauthenticated users. Only the basic meta-information for a user is represented and stored by this class: if you want a more articulated idea of a user, either subclass us or build another module that adds it in another table. Eventually, I will make this more flexible.

One cool thing about even this current, stupid implementation is that non-nobody users can have persistent preferences, which mirror the status of the variables in their latest Session by default. This means that the default values for creating a new session for a user come from the preferences they saved last time, without any additional work on your part. Yay.

The other major piece of heavy lifting that we perform in this module is to implement a standard, email-based registration process for new users. This is accomodated in our database schema, as well, and is mainly transparent to the actual webapp, which must simply supply a tiny bit of glue for it all to work. The idea is as follows: the webapp will have some sort of user registration page, on which a potential user fills in their desired user name, password, email address, and other information. This is used to create an initial, unconfirmed user entry. Unconfirmed users exist in the database, but cannot be used for anything except confirming themselves. When a new, unconfirmed user is created (via our constructor, just like you would expect), an email is sent to the email address that the user gave containing instructions on how to finish creating their account. This email will most likely contain an URL for them to click on, or at the very least their confirmation token, which is an MD5 of some stuff that they gave us and some stuff that they have no way of finding out.

The glue that the actual webapp must provide are the means for either entering the confirmation token, or for handling the URL we send them in email. All that must occur is that our constructor be called with the same parameters as were used to create the unconfirmed user, plus a single additional piece of information, namely, their confirmation token. If this is done, the users status is changed to confirmed, and the WebApp::User is live, and able to be used for whatever purpose.

DETAILED DOCUMENTATION

ConfirmationString $uid,$email,$password

GC $dbh|$dsn[,LIMIT => $time_limit, DBUSER => $user, DBPASS => $pass]

Garbage collects unconfirmed users whose records have not been updated in $time_limit seconds (default is 7 days). This should be run periodically against a webapp database for which open user registration is enabled, to keep unconfirmed users from clogging up the works. Any active sessions for the users we find are also cleaned up.

The only required parameter is positional, and should either be an active DBI database handle, or a DSN string that can be used to construct one. If GC builds its own handle, it tears it down when it finishes. If you want to override the defaults for username and password (which are just $ENV{USER} and the empty string), then pass the DBUSER and DBPASS arguments.

id

Return the user ID, a short, descriptive name.

name

Return the name the users mother chose for them (theoretically).

email

Return the email address the user gave us.

class

Return the class of user, a single letter that can stand for whatever you want it to stand for. For instance, A might mean administrator, and U might mean normal user. Or not.

password

Return the users password. We should really store a hash. Damn.

confirmation

Return the users confirmation token.

is_fresh

Returns non-zero if the user was just freshly created.

is_confirmed

Returns non-zero if the user is confirmed.

ttl

Returns the session TTL for this user.

delete [$dbh]

Delete the user from the database. If no DBI handle is given, then the one in the object itself is used.

as_string

Return a human-readable representation of ourselves.

dump [$fh]

Dump ourselves out to a file handle (STDERR by default)

is_nobody

Returns non-zero if this User stands for the special "nobody" user that should be given minimal, if any, rights.

copy_vars $hashref

Merge a hashref into our list of variables.

set_var $name,$val

Set a variables value, creating it if it does not exist.

add_var $name,$val

Add a variable to a user, returning an error if it already existed.

delete_var $name[,$name2...]

have_var $name

Return non-zero if the user has a variable with the given name.

get_vars

Return the hashref of all our variables. Ugly.

get_var $name

Get the named variables value.

store [$dbh]

Store ourselves into a DBI database. We flush any prior state for the user and the store our new state.

new [args=>values]

Constructify a user. Takes the following named arguments:

Database handleto use: not option, must be supplied or we croak.

user

UserID to look up or create; must be supplied or we croak.

password

Password for the new user (or to check an existing user). Can be blank if NO_CHECK is specified.

name

Name for the user. Must be a nonempty string.

Email address for the user. Must be a nonempty string that looks like an Email address.

class

A one-character classification for the user that is up to the application to interpret and enforce.

CONFIRMED

If specified, then we are completing the user registration process for this user, and the value of the CONFIRMED argument is the confirmation token, which must match that on record in the database for this user.

CREATE

A flag: if set, an attempt is made to create a new user with the information given in the other arguments. In this case, it is an error if the user already exists.

NO_CHECK

A flag: if set, password checking is not done, only a valid User ID need be given.

SEND_EMAIL

A flag: if set, initiate the email-based user registration process.

SMTP_SERVER

Only applies if SEND_EMAIL: SMTP server to use, default is localhost:25

SMTP_TIMEOUT

Only applies if SEND_EMAIL: Timeout, in seconds, for SMTP operations.

SMTP_HELLO

Only applies if SEND_EMAIL: HELO value to send to the SMTP server.

SMTP_DEBUG

Only applies if SEND_EMAIL: turn Net::SMTP debugging on.

List $dbh

Return a list of user ids in the given database

DDL [$dbh|$dsn]

Execute the WebApp::User DDL against a DBI database, to initialize it for use with webapp.

AUTHOR

Sean Levy <mailto:snl@cluefactory.com>

COPYRIGHT AND LICENSE

This code is released under a BSD license. Please see the LICENSE file that came with the source distribution or visit http://cluefactory.com/oss/WebApp/license.html