Core Boxx – Users Module

Last Updated: September 12, 2023

TABLE OF CONTENTS

 

DOWNLOAD & INSTALLATION

First, the download links for the module, and also “installation instructions”.

 

LICENSE & DOWNLOAD

GitHub | Source Forge

Core Boxx is released under the MIT License. You are free to use it for personal and commercial projects, and modify it as you see fit. On the condition that the software is provided “as-is”. There are no warranties provided and “no strings attached”. Code Boxx and the authors are not liable for any claims, damages, or liabilities.

 

INSTALLATION

  • Copy/unzip this module into your existing Core Boxx project folder.
  • Access http://your-site.com/install/users, this will automatically:
    • Import lib/SQL-Users.sql into your database.
    • Add a new USR_LVL definition into lib/CORE-Config.php.
    • Update lib/HOOK-SESS-Save.php to save only the user ID into the JWT.
    • Update lib/HOOK-SESS-Load.php to load user data from the database into $_SESSION.
    • Delete PAGE-install-users.php itself.

 

SORRY FOR THE ADS...

But someone has to pay the bills, and sponsors are paying for it. I insist on not turning Code Boxx into a "paid scripts" business, and I don't "block people with Adblock". Every little bit of support helps.

Buy Me A Coffee Code Boxx eBooks

 

 

FILES LIST

LIBRARIES

  • lib/LIB-Forgot.php Forgot password library.
  • lib/LIB-Users.php Users library.
  • lib/SQL-Users.php User and forgot password database tables.

API

  • lib/API-session.php To process login, logout, forgot password, register, “update my account”.
  • lib/API-user.php Admin user functions.

ASSETS & PAGES

  • pages/PAGE-forgot.php Forgot password page.
  • assets/forgot.webp Forgot password page image.
  • assets/PAGE-forgot.js Forgot password page Javascript.
  • pages/MAIL-forgot-a.php Email template – Click to confirm reset.
  • pages/MAIL-forgot-b.php Email template – New password.
  • pages/PAGE-login.php User login page.
  • assets/login.webp Login page image.
  • assets/PAGE-login.js Login page Javascript.
  • pages/PAGE-myaccount.php My account page.
  • assets/PAGE-myaccount.js My Account page Javascript.
  • pages/PAGE-register.php Register account page.
  • assets/PAGE-register.js Register account page Javascript.
  • pages/PAGE-activate.php Activate account page.
  • pages/MAIL-activate.php Activate account email template.
  • assets/PAGE-activate.js Activate account page Javascript.

 

DATABASE REFERENCE

The users module will create 2 tables – One for the users, and another “shared” hash table for activation and forgotten passwords.

 

USER TABLE

Field Description
user_id Primary key. The user ID.
user_level User level (or user role).

  • A – Admin
  • U – User
  • S – Suspended

Feel free to add your own.
user_name The user’s name.
user_email The user’s email address, unique to prevent multiple registrations.
user_password The user’s password.

USER HASH TABLE

Function Description
user_id Primary and foreign key, the user ID.
hash_for Primary key, what this hash/credential is used for.

  • A – Account activation.
  • P – Forgot password.
  • OTP – One time password.
  • GOO – Login With Google, linked Google account ID.
  • NFC – Login With NFC, encrypted login credential.
  • PLC – Passwordless login challenge.
  • PL – Passwordless login credential.

Feel free to add more.
hash_code Random hash code or credential.
hash_time When the request or credential is created. Use this to calculate the validity time, expiry, and to prevent spam.
hash_tries To keep track of the number of tries. If you want to do rate limiting, or “strike” after a certain number of fails.

 

 

LIBRARY REFERENCE

Lastly, the list of library functions and API endpoints.

 

USER LIBRARY

HELPER FUNCTIONS

checker ($password, $pattern)

Checks if the given password is secure.

  • $password String, password to check.
  • $patter Regex, defaults to “at least 8 characters alphanumeric”.
echo $_CORE->Users->checker("F00BarF1x")
  ? "OK" : "NOPE" ;

 

GET USER FUNCTIONS

get ($id, $hash)

Get a user by ID or email.

  • $id Int OR string, the user ID or email.
  • $hash NULL OR string, also include validation hash.
$user = $_CORE->Users->get(999);
$user = $_CORE->Users->get("john@doe.com");
getAll ($search, $page)

Get all or search for users.

  • $search String, optional name/email search.
  • $page Integer, current page number.
$users = $_CORE->Users->getAll("jo", 3);

 

SAVE & DELETE USER FUNCTIONS

save ($name, $email, $password, $lvl, $id)

Add a new user, or update an existing user.

  • $name String, the user name.
  • $email String, the user email.
  • $password String, the user’s password, in cleartext.
  • $lvl String, the user level.
  • $id Int, pass in the user ID if you want to update an existing user.
echo $_CORE->Users->save(
  "Jon Doe", "jon@doe.com", "PASSWORD", "U"
) ? "OK" : $_CORE->error ;
del ($id)

Deletes a user.

  • $id Int, the user ID.
echo $_CORE->Users->del(999) ? "OK" : $_CORE->error ;
suspend ($id)

Suspend a user. A softer approach to delete, if you want to retain user data.

  • $id Int, the user ID.
echo $_CORE->Users->suspend(999) ? "OK" : $_CORE->error ;
update ($name, $cpass, $pass)

Restricted “update user”. Must be signed in, can only update own account.

  • $name String, the user name.
  • $cpassString, current password.
  • $pass String, new password.
echo $_CORE->Users->update(
  "Jon Doe", "OLD PASSWORD", "NEW PASSWORD"
) ? "OK" : $_CORE->error ;

 

 

VERIFY, LOGIN, LOGOUT

verify ($email, $password)

Verify the given email and password. Returns the user array if valid, false if invalid.

  • $email – String, email.
  • $password – String, password.
$user = $_CORE->Users->verify("john@doe.com", "PASSWORD");
if (is_array($user)) { VALID }
else { INVALID }
login ($email, $password)

User login sequence. Generates and registers a jwt cookie.

  • $email – String, email.
  • $password – String, password.
if ($_CORE->Users->login("john@doe.com", "PASSWORD")) {
  REDIRECT TO HOME PAGE
}
logout ()

User logout sequence. Destroys jwt cookie.

if ($_CORE->Users->logout()) {
  REDIRECT TO HOME PAGE
}

 

USER REGISTRATION & ACTIVATION

register ($name, $email, $password)

This is a restricted “add user” for use on the front end. You can modify this function to send a confirmation email, or maybe restrict the “user level” to “customer”.

  • $name String, the user name.
  • $email String, the user email.
  • $password String, the user’s password, in cleartext.
echo $_CORE->Users->register(
  "Jon Doe", "jon@doe.com", "PASSWORD"
) ? "OK" : $_CORE->error ;
hsend ($id)

For account activation, generate a random hash and send an activation link.

  • $id Int, the user ID.

NOTE: Complete your own email format.

echo $_CORE->Users->hsend(123) ? "OK" : $_CORE->error ;
hactivate ($i, $h)

Activate account challenge.

  • $i Int, user ID.
  • $h String, the random hash.
echo $_CORE->Users->hactivate(123, "ABC12345DEF") ? "OK" : $_CORE->error ;

 

 

USER HASH

hashAdd ($id, $for, $code, $time)

Add a user hash or credential.

  • $id INT, the user ID.
  • $for STRING, see hash_for above.
  • $code STRING, hash or credential.
  • $time Timestamp.
    • NULL Use the current timestamp.
    • STRING Use your defined timestamp.
    • "" Don’t change.
$_CORE->Users->hashAdd(123, "GOO", GOOGLE-ID);
hashGet ($id, $for)

Get user hash.

  • $id INT, the user ID.
  • $for STRING, see hash_for above.
$hash = $_CORE->Users->hashGet(123, "GOO");
hashDel ($id, $for)

Remove user hash or credential.

  • $id INT, the user ID.
  • $for STRING, see hash_for above.
$_CORE->Users->hashDel(123, "GOO");

 

FORGOTTEN PASSWORD LIBRARY FUNCTIONS

request ($email)

Step 1 – Generate a random security hash, and send the reset link to the user.

  • $email The user’s email.

NOTE: Complete your own email format.

reset ($id, $hash)

Step 2 – Validate the hash, generate a new random password, and email it to the user.

  • $id The user ID.
  • $hash The security hash.

NOTE: Remember to format your own emails.

 

USER API FUNCTIONS

api/users/get/

Get a user by ID or email.

  • $_POST["id"] – Int or string, user ID or email.
api/users/getAll/

Get all or search for users.

  • $_POST["search"] – String, optional name/email.
  • $_POST["page"] – Int, optional current page number.
api/users/save/

Add or update the user.

  • $_POST["name"] String, the user name.
  • $_POST["email"] String, the user email.
  • $_POST["password"] String, the user’s password, in cleartext.
  • $_POST["level"] String, user-level (“U”ser, “A”dmin, “E”ditor, etc…)
  • $_POST["id"] Int, optional. Pass in the user ID to update instead of insert.
api/users/del/

Delete a user.

  • $_POST["id"] Int, the user ID.

 

 

SESSION API FUNCTIONS

api/session/login/

Process user login.

  • $_POST["email"] String, the email.
  • $_POST["password"] String, the password.
api/session/logout/

Process user logoff.

api/session/register/

Registers a new user.

  • $_POST["name"] String, user name.
  • $_POST["email"] String, user email.
  • $_POST["password"] String, the password.
api/session/activate/

Resend the activation link.

  • $_POST["id"] Int, user ID.
api/session/update/

Update “my account”. The user must be signed in.

  • $_POST["name"] String, user name.
  • $_POST["email"] String, user email.
  • $_POST["password"] String, the password.
api/session/forgotA

Step 1 – Generate a random security hash, send the reset link to the user.

  • $_POST["email"] String, the user’s email.
api/session/forgotB

Step 2 – Validate the hash, generate a new random password, and email it to the user.

  • $_POST["id"] The user ID.
  • $_POST["hash"] The security hash.

 

2 thoughts on “Core Boxx – Users Module”

Comments are closed.