User::...::Admin(3pm)

✨ NAME ✨

User::Simple::Admin — okay so this is the user administration half of the User::Simple situation 💅

---

✨ 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 ✨

So User::Simple::Admin runs the administrative side of the User::Simple modules. Bestie, go peek at User::Simple itself for the big-picture overview of these modules and the whole explanation of what-goes-where, fr fr 🌸

Here's the vibe: User::Simple::Admin acts like a regular administrator would. You should instantiate the module once for all of your users' administration, if possible — not once per user. That's the opposite (contraposition, iconic word) of User::Simple, which works from each of the users' perspective in independent instantiations 👑

Also, real talk: User::Simple::Admin does not do the administrative user checks. It's meant to be integrated into your system, and it is your system that should carry out all of the needed authentication checks. Not me, not the module, your system. Periodt 💅

---

🎀 CONSTRUCTOR 🎀

Administrative actions for the 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.

Now — if we don't yet have the DB structure we need to store the user information, we can use this class method as a constructor too:

  $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 is the one you want if your DBI handle ($db) points to a real RDBMS, like PostgreSQL or MySQL 💖 In case you're using a file-based DBD (think DBD::XBase, DBD::DBM, DBD::CVS or literally any other one that doesn't use a real RDBMS for storage), use User::Simple::Admin->create_plain_db_structure instead.

What's the difference, you ask? 🦋 In the first case we 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. Which, of course, cannot be achieved using file-based structures, so the integrity can only be maintained from within our scripts. Sad but true 😭

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), because many DBDs do not implement the ALTER TABLE SQL commands. It does, however, let you specify extra fields in the tables at creation time ✨ If you specify a third extra parameter, it gets included as part of the table creation. So like, you can create a User::Simple table with fields for the user's first and family names plus a UNIQUE constraint over them, like this:

  $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 ;-) And avoid adding any fields starting with "set_" or called as any method defined here, because they will become unreachable 🫶 And of course, keep in mind what SQL construct your DBD supports, bestie.

If you add any fields with names starting with "adm_", they will be visible but not modifiable from within User::Simple — you'll 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. And heads up: 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. Bye bestie 👋

  $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, but every other method answers only to the ID. So 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. And 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. That's just how it is, bestie.

---

🍓 DEPENDS ON 🍓

Digest::MD5

---

🌟 SEE ALSO 🌟

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

---

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

---

And that's the whole page, bestie! 💅 This lil' doc shipped with perl v5.34.0 and was dated 2022-06-28 — it's giving vintage but make it iconic ✨ slay, go admin some users 🎀