User::Simple::Admin(3pm)				User Contributed Perl Documentation				  User::Simple::Admin(3pm)

NAME

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

SYNOPSIS

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

	 $ua = User::Simple::Admin->create_rdbms_db_structure($db, $user_table,
	     [$extra_sql]);
	 $ua = User::Simple::Admin->create_plain_db_structure($db, $user_table,
	     [$extra_sql]);
	 $ok = User::Simple::Admin->has_db_structure($db, $user_table);

	 %users = $ua->dump_users;

	 $id = $ua->id($login);
	 $login = $ua->login($id);

	 $otherattrib = $user->otherattrib($id);

	 $ok = $usr->set_login($id, $login);
	 $ok = $usr->set_passwd($id, $passwd);
	 $ok = $usr->set_otherattrib($id, $value);
	 $ok = $usr->clear_session($id);

	 $id = $ua->new_user(login => $login, passwd => $passwd,
	       [otherattribute => $otherattribute]);

	 $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, and 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.

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

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

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

       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_rdbms_db_structure($db, $user_table,
	     [$extra_sql]);

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

       The first one should be used if your DBI handle ($db) points to a real RDBMS, such as PostgreSQL or MySQL. In case you are using a file-
       based DBD (such as DBD::XBase, DBD::DBM, DBD::CVS or any other which does not use a real RDBMS for storage), use
       "User::Simple::Admin->create_plain_db_structure" instead. What is the difference? In the first case, we will create a table that has
       internal consistency checks - Some fields are declared NOT NULL, some fields are declared UNIQUE, and the user ID is used as a PRIMARY KEY.
       This cannot, of course, be achieved using file-based structures, so the integrity can only be maintained from within our scripts.

       This module does not provide the functionality to modify the created tables by adding columns to it, although methods do exist to access
       and modify the values stored in those columns (see the "CREATING, QUERYING AND MODIFYING USERS" section below), as many DBDs do not
       implement the ALTER TABLE SQL commands. It does, however, allow you to specify extra fields in the tables at creation time - If you specify
       a third extra parameter, it will be included as part of the table creation - i.e., you can create a User::Simple table with fields for the
       user's first and family names and a UNIQUE constraint over them this way:

	 $ua = User::Simple::Admin->create_rdbms_db_structure($db, $user_table,
	     'firstname varchar(30) NOT NULL, famname varchar(30) NOT NULL,
	      UNIQUE (firstname,famname)');

       Keep in mind that the internal fields are "id", "login", "passwd", "session" and "session_exp". Don't mess with them ;-) Avoid adding any
       fields starting with "set_" or called as any method defined here, as they will become unreachable. And, of course, keep in mind what SQL
       construct does your DBD support.

       If you add any fields with names starting with "adm_", they will be visible but not modifiable from within User::Simple - You will only be
       able to modify them from User::Simple::Admin.

   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 with all of the existing DB fields, in the following form:

	 ( $id1 => { login=>$login1, firstname=>$firstname1, famname=>$famname1 },
	   $id2 => { login=>$login2, firstname=>$firstname2, famname=>$famname2 },
	   (...) )

       Of course, with the appropriate attributes. The internal attributes "id", "session" and "session_exp" will not be included in the resulting
       hashes (you have the "id" as the hash keys).

   CREATING, QUERYING AND MODIFYING USERS
	 $id = $ua->new_user(login => $login, passwd => $passwd,
	       [otherattribute => $otherattribute]);

       Creates a new user with the specified data. Returns the new user's ID. Only the login is mandatory (as it uniquely identifies the user),
       unless you have specified extra NOT NULL fields or constraints in the DB. If no password is supplied, the account will be created, but no
       login will be allowed until one is supplied.

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

       Removes the user specified by the ID.

	 $id = $ua->id($login);
	 $login = $ua->login($id);

	 $otherattrib = $user->otherattrib($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 firstname, you can use "$ua-"firstname($ua->id($login));>

       Of course, beware: if you request for a field which does not exist in your table, User::Simple will raise an  error and die just as if an
       unknown method had been called.

	 $ok = $usr->set_login($id, $login);
	 $ok = $usr->set_passwd($id, $passwd);

       Modifies the requested attribute of the specified user, setting it to the new value. Except for the login, they can all be set to null
       values - If the password is set to a null or empty value, the account will be locked (that is, no password will be accepted). The internal
       attributes "id", "session" and "session_exp" cannot be directly modified (you have the "id" as the hash keys).

       Just as with the accessors, if you have extra columns, you can modify them the same way:

	 $ok = $usr->set_otherattrib($id, $value);

       i.e.

	 $ok = $usr->set_name($id, $name);

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

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

perl v5.10.0							    2009-01-20						  User::Simple::Admin(3pm)