User::Simple(3pm)

💖 NAME 💖

User::Simple — simple user sessions management, bestie. That's it, that's the whole vibe. 👑

---

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

like… look at her. she's so clean. 🫶

---

🌸 DESCRIPTION 🌸

okay so User::Simple gives you a very simple framework for validating users, managing their sessions, and storing a minimal little set of information — literally just a meaningful user login/password pair, and the privilege level — all via a database. but here's the slay part: it also gives you a transparent way to reach any other attributes you decide to define. ✨

those sessions? you can use them as identifiers for, like, cookies on a Web system. iykyk. and the passwords are stored as MD5 hashes — meaning the password is never stored in clear text. no cap, we love a security moment. 🔥

User::Simple was originally developed with a PostgreSQL database in mind, but it 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. it's giving strict. 💅

the functionality is split into two modules: User::Simple and User::Simple::Admin. this module is the one that 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 that don't begin with adm_. 🎀

⚠️ heads up bestie: you cannot directly modify a user's login, session or session expiry from within this module. and like, 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]);

obviously the database must have the right structure in it — please check User::Simple::Admin for more info. 📚

the tbl parameter is the name of the table where the user information is stored. if you don't specify it, it defaults to 'user_simple'. 🏠

durat is the number of minutes a user's session should last. its default is 30 minutes. ⏰

debug is the verbosity level of the debugging messages — the default is 2, and 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, and 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! not the vibe for production, bestie, fr fr.

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

---

and that's the whole page, bestie!! 💖 this lil icon was living in perl v5.34.0, dated 2022-06-28 — and honestly? she ate. go build something cute with her, mwah 💅✨🌸