Core Boxx – Users Module

By / Project Documentation / January 18, 2022

This is a simple user’s module for Core Boxx – Comes complete with user registration, login, logout, forgot password recovery. Of course, feel free to modify or remove whatever you need.

 

TABLE OF CONTENTS

Download & Notes Quick Start Quick Reference

 

 

DOWNLOAD & NOTES

First, here are the download links and a quick “setup guide” for the impatient folks who don’t want to read through everything.

 

LICENSE & DOWNLOAD

Core Boxx is released under the MIT License. You are free to use it for personal and commercial projects, modify 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 & REQUIREMENTS

  • Download and set up the “Main Core Boxx” if you have not already done so.
  • The Mail Module is required to reset forgotten passwords.
  • Import lib/SQL-users.sql into your database.
  • See “quick start” below.

 

QUICKSTART

This user module uses JSON Web Token (JWT) to drive the user sessions.

 

STEP 1) CONFIG & CORE SEQUENCE

  • Open lib/CORE-config.php, enable the entire JWT section. Generate your own random secret key, fill in your company or website name (issuer).
  • Open lib/CORE-go.php, enable $_CORE->load("Session").

 

STEP 2) CREATE A USER

Access http://site.com/register, create your own dummy user.

 

 

STEP 3) LOGIN

  • The default login page is at http://site.com/login.
  • It does an API call to http://site.com/api/session/login with $_POST["EMAIL"] and $_POST["PASSWORD"].
  • You can also manually call $_CORE->Users->login("EMAIL", "PASSWORD") if you want.

 

STEP 4) LOGOUT

  • The default logout page is at http://site.com/logout.php.
  • Or you can just do an API call to http://site.com/session/logout

 

STEP 5) FORGOTTEN PASSWORDS

  • The default password reset page is at http://site.com/forgot.
  • The password recovery email templates are at page/MAIL-forgot-a.php and page/MAIL-forgot-b.php. Edit these to create your own “nice emails”.

 

QUICK REFERENCE

This section is a quick walkthrough of the general module structures.

 

THE USER TABLE

Field Description
user_id Primary key. The user ID.
user_name The user’s name.
user_email The user’s email address, unique to prevent multiple registrations.
user_password The user’s password.

 

 

FORGOTTEN PASSWORD DATABASE TABLE

Function Description
user_id Primary and foreign key, the user ID.
reset_hash A randomly generated hash to validate the reset.
reset_time When the request is made. Use to calculate the validity time, and to prevent spam.

 

USER LIBRARY FUNCTIONS

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

Add a new user, or update an existing user.

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

This is a restricted “add user” for use on the front-end.

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

Deletes a user.

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

Get a user by ID or email.

  • $id Int OR string, the user ID or email.
$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);
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
}

 

 

SESSION LIBRARY FUNCTIONS

__construct()

Automatically reads $_COOKIE["cbsess"] if it exists, and parses the data into $_SESS.

create()

Grabs all data from $_SESS and generates a new $_COOKIE["cbsess"].

destroy()

Clears $_SESS and destroys $_COOKIE["cbsess"].

 

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, 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 to the user.

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

NOTE: Remember to format your own emails.

 

 

USER API FUNCTIONS

Accessible at http://yoursite.com/api/users/REQUEST/. These are pretty much a replica of the above library functions, except in REST API format. Feel free to delete if you don’t intend to integrate an API.

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

Accessible at http://yoursite.com/api/session/REQUEST/.

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/forgot/forgotA

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

  • $_POST["email"] String, the user’s email.
api/forgot/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.

Leave a Comment

Your email address will not be published.