Core Boxx - Users Module

Download & Installation

Database Reference

Library Reference

DOWNLOAD & INSTALLATION

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

LICENSE & DOWNLOAD

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.

Download Core Boxx Users Module | GitHub | Source Forge

INSTALLATION

Install the “main” Core Boxx first, then unzip this module into your existing Core Boxx project folder.
Import lib/SQL-Users.sql into your database.
Copy the snippet from lib/CORE-Config.add into lib/CORE-Config.php.
Copy the snippet from lib/HOOK-SESS-Load.add into lib/HOOK-SESS-Load.php.
Copy the snippet from lib/HOOK-SESS-Save.add into lib/HOOK-SESS-Save.php.

FILES LIST

LIBRARIES

lib/LIB-Forgot.php Forgot password library.
lib/LIB-Users.php Users library.
lib/CORE-Config.add Additional user-level definitions.
lib/HOOK-SESS-Load.add Load user from database to session information when parsing the JWT.
lib/HOOK_SESS-Save.add Only save the user ID into the JWT.
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 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 is used for. A – Account activation. P – Forgot password. O – OTP Feel free to add more.
`hash_code`	Random hash code.
`hash_time`	When the request is made. Use to calculate the validity time, 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 ;

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 }

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

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 ;

FORGOTTEN PASSWORD LIBRARY FUNCTIONS

get($id)

Get a password reset request.

$id Int, the request ID.

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