NAME

User::Simple::Admin - User::Simple user administration

SYNOPSIS

$ua = User::Simple::Admin->new($db, $user_table, [$adm_level]);

$ua = User::Simple::Admin->create_db_structure($db, $user_table, 
                                               [$adm_level]);
$ok = User::Simple::Admin->has_db_structure($db, $user_table);

%users = $ua->dump_users;

$id = $ua->id($login);
$login = $ua->login($id);
$name = $ua->name($id);
$level = $ua->level($id);
$is_admin = $ua->is_admin($id);

$ok = $usr->set_login($id, $login);
$ok = $usr->set_name($id, $name);
$ok = $usr->set_level($id, $level);
$ok = $usr->set_admin($id);
$ok = $usr->unset_admin($id);
$ok = $usr->set_passwd($id, $passwd);
$ok = $usr->clear_session($id);

$id = $ua->new_user($login, $name, $passwd, $level);

$ok = $ua->remove_user($id);

DESCRIPTION

User::Simple::Admin manages the administrative part of the User::Simple modules - Please check User::Simple for a general overview of these modules and an explanation on what-goes-where.

User::Simple::Admin works as a regular administrator would: The module should be instantiated only once for all of your users' administration, if possible, not instantiated once for each user (in contraposition to User::Simple, as it works from each of the users' perspective in independent instantiations).

Note also that User::Simple::Admin does b<not> perform the administrative user checks - It is meant to be integrated to your system, and it is your system which should carry out all of the needed authentication checks.

There are some oddly named methods and attributes you will find both in User::Simple and this modules - is_admin, set_admin, unset_admin, adm_level. Please consider them all as deprecated. They are provided only for backward compatibility, and will be dropped in a future version.

CONSTRUCTOR

Administrative actions for User::Simple modules are handled through this Admin object. To instantiate it:

$ua = User::Simple::Admin->new($db, $user_table, [$adm_level]);

$db is an open connection to the database where the user data is stored.

$user_table is the name of the table that holds the users' data.

The optional $adm_level argument indicates from which level on are users recognized as administrative - This can be any arbitrary nonnegative integer. If this parameter is not specified, it will default to 1, having basically a correspondence to Perl's handling of truth values.

If we do not yet have the needed DB structure to store the user information, we can use this class method as a constructor as well:

$ua = User::Simple::Admin->create_db_structure($db, $user_table,
                                               [$adm_level])

QUERYING FOR DATABASE READINESS

In order to check if the database is ready to be used by this module with the specified table name, use the has_db_structure class method:

$ok = User::Simple::Admin->has_db_structure($db, $user_table);  

RETRIEVING THE SET OF USERS

%users = $ua->dump_users;

Will return a hash with the data regarding the registered users, in the following form:

( $id1 => { level => $level1, is_admin => $is_admin1, 
            name => $name1, login => $login1},
  $id2 => { level => $level2, is_admin => $is_admin2,
            name => $name2, login => $login2},
  (...) )

CREATING, QUERYING AND MODIFYING USERS

$id = $ua->new_user($login, $name, $passwd, $level);

Creates a new user with the specified data. $is_admin is a boolean value - Use 1 for true, 0 for false. Returns the new user's ID.

$ok = $ua->remove_user($id);

Removes the user specified by the ID.

$id = $ua->id($login);
$login = $ua->login($id);
$name = $ua->name($id);
$level = $ua->level($id);
$is_admin = $ua->is_admin($id);

Get the value of each of the mentioned attributes. Note that in order to get the ID you can supply the login, every other method answers only to the ID. In case you have the login and want to get the name, you should use $ua-name($ua->id($login));>

$ok = $usr->set_login($id, $login);
$ok = $usr->set_name($id, $name);
$ok = $usr->set_passwd($id, $passwd);
$ok = $usr->set_level($id, $level);

Modifies the requested attribute of the specified user, setting it to the new value.

$ok = $usr->set_admin($id);
$ok = $usr->unset_admin($id);

Sets or removes the administrative status of this user. Please note that this is done relative to the value specified as $adm_level upon the User::Simple::Admin object's instantiation - By calling set_admin, the user's level will be set to the minimum administrative value (this means, to the current $adm_level). By calling unsed_admin, it will be set to zero.

Note that the set_admin and unset_admin methods are provided for backwards compatibility and should be considered as deprecated - In order to set a user's level, you should call set_level instead. Support for these two methods (and to the is_admin idea in general) will be dropped in the future.

SESSIONS

$ok = $usr->clear_session($id);

Removes the session which the current user had open, if any.

Note that you cannot create a new session through this module - The only way of creating a session is through the ck_login method of User::Simple.

DEPENDS ON

Digest::MD5

SEE ALSO

User::Simple for the regular user authentication routines (that is, to use the functionality this module adimisters)

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.