Core Boxx - Users Module

INTRODUCTION

This is a simple user’s module for Core Boxx, it is actually a “package of 3 components”:

Session – Not the “traditional” PHP $_SESSION, but JSON Web Token to also support mobile apps.
User – User registration, login, and logout.
Forgot password recovery.

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 you existing Core Boxx project folder.
Import lib/SQL-Users.sql into your database.
If you want to allow users to reset their own passwords, also import lib/SQL-Forgot.sql.
In the lib/Core-Config.php:
- Enable the entire JSON Web Token section.
- Set your own secret key JWT_SECRET (or generate a random one).
- Change JWT_ISSUER to your business/blog/site name.
Edit lib/CORE-Go.php and load $_CORE->load("Session") by default.

USERS & SESSIONS FILES

jwt/ Firebase PHP JSON Web Token library.
lib/LIB-Session.php JSON Web Token session library.
lib/LIB-Users.php Users library.
lib/API-session.php JSON Web Token session API.
lib/API-users.php Users API.
pages/PAGE-register.php User account registration page.
assets/PAGE-register.js User account registration page Javascript.
pages/PAGE-login.php Login page.
assets/PAGE-login.js Login page Javascript.
pages/PAGE-myaccount.php “My Account” page.
assets/PAGE-myaccount.js “My Account” page Javascript.

FORGOTTEN PASSWORD FILES

lib/LIB-Forgot.php Password recovery library.
pages/PAGE-forgot.php Password recovery page.
assets/PAGE-forgot.js Password recovery Javascript.
pages/MAIL-forgot-a.php Email template, “click on this link to reset password”.
pages/MAIL-forgot-b.php Email template, “this is your new password”.

USERS & SESSIONS REFERENCE

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.

USER LIBRARY 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" ;

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 ;

update($name, $email, $password)

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

$name String, the user name.
$emailString, the user email.
$password String, the user’s password, in cleartext.

echo $_CORE->Users->update(
  "John Doe", "john@doe.com", "PASSWORD"
) ? "OK" : $_CORE->error ;

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 }

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"].

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

FORGOTTEN PASSWORD REFERENCE

FORGOT PASSWORD 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.

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)